

<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="./">
<head>
  <meta charset="utf-8" />
  <meta name="readthedocs-addons-api-version" content="1"><meta name="viewport" content="width=device-width, initial-scale=1" />

  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>UCI/XBoard engine communication &mdash; python-chess 1.11.2 documentation</title>
      <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=03e43079" />
      <link rel="stylesheet" type="text/css" href="_static/css/theme.css?v=e59714d7" />

  
      <script src="_static/jquery.js?v=5d32c60e"></script>
      <script src="_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
      <script src="_static/documentation_options.js?v=ff71f5f3"></script>
      <script src="_static/doctools.js?v=9bcbadda"></script>
      <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
    <script src="_static/js/theme.js"></script>
    <script src="_static/js/versions.js"></script>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="SVG rendering" href="svg.html" />
    <link rel="prev" title="Syzygy endgame tablebase probing" href="syzygy.html" /> 
<script async type="text/javascript" src="/_/static/javascript/readthedocs-addons.js"></script><meta name="readthedocs-project-slug" content="python-chess" /><meta name="readthedocs-version-slug" content="latest" /><meta name="readthedocs-resolver-filename" content="/engine.html" /><meta name="readthedocs-http-status" content="200" /></head>

<body class="wy-body-for-nav"> 
  <div class="wy-grid-for-nav">
    <nav data-toggle="wy-nav-shift" class="wy-nav-side">
      <div class="wy-side-scroll">
        <div class="wy-side-nav-search" >

          
          
          <a href="index.html" class="icon icon-home">
            python-chess
          </a>
              <div class="switch-menus">
                <div class="version-switch"></div>
                <div class="language-switch"></div>
              </div>
<div role="search">
  <form id="rtd-search-form" class="wy-form" action="search.html" method="get">
    <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
    <input type="hidden" name="check_keywords" value="yes" />
    <input type="hidden" name="area" value="default" />
  </form>
</div>
        </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
              <ul class="current">
<li class="toctree-l1"><a class="reference internal" href="core.html">Core</a></li>
<li class="toctree-l1"><a class="reference internal" href="pgn.html">PGN parsing and writing</a></li>
<li class="toctree-l1"><a class="reference internal" href="polyglot.html">Polyglot opening book reading</a></li>
<li class="toctree-l1"><a class="reference internal" href="gaviota.html">Gaviota endgame tablebase probing</a></li>
<li class="toctree-l1"><a class="reference internal" href="syzygy.html">Syzygy endgame tablebase probing</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">UCI/XBoard engine communication</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#playing">Playing</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#chess.engine.Protocol"><code class="docutils literal notranslate"><span class="pre">Protocol</span></code></a><ul>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Protocol.play"><code class="docutils literal notranslate"><span class="pre">Protocol.play()</span></code></a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#chess.engine.Limit"><code class="docutils literal notranslate"><span class="pre">Limit</span></code></a><ul>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Limit.time"><code class="docutils literal notranslate"><span class="pre">Limit.time</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Limit.depth"><code class="docutils literal notranslate"><span class="pre">Limit.depth</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Limit.nodes"><code class="docutils literal notranslate"><span class="pre">Limit.nodes</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Limit.mate"><code class="docutils literal notranslate"><span class="pre">Limit.mate</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Limit.white_clock"><code class="docutils literal notranslate"><span class="pre">Limit.white_clock</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Limit.black_clock"><code class="docutils literal notranslate"><span class="pre">Limit.black_clock</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Limit.white_inc"><code class="docutils literal notranslate"><span class="pre">Limit.white_inc</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Limit.black_inc"><code class="docutils literal notranslate"><span class="pre">Limit.black_inc</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Limit.remaining_moves"><code class="docutils literal notranslate"><span class="pre">Limit.remaining_moves</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Limit.clock_id"><code class="docutils literal notranslate"><span class="pre">Limit.clock_id</span></code></a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#chess.engine.PlayResult"><code class="docutils literal notranslate"><span class="pre">PlayResult</span></code></a><ul>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.PlayResult.move"><code class="docutils literal notranslate"><span class="pre">PlayResult.move</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.PlayResult.ponder"><code class="docutils literal notranslate"><span class="pre">PlayResult.ponder</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.PlayResult.info"><code class="docutils literal notranslate"><span class="pre">PlayResult.info</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.PlayResult.draw_offered"><code class="docutils literal notranslate"><span class="pre">PlayResult.draw_offered</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.PlayResult.resigned"><code class="docutils literal notranslate"><span class="pre">PlayResult.resigned</span></code></a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#id0"><code class="docutils literal notranslate"><span class="pre">Protocol</span></code></a><ul>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Protocol.send_opponent_information"><code class="docutils literal notranslate"><span class="pre">Protocol.send_opponent_information()</span></code></a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#chess.engine.Opponent"><code class="docutils literal notranslate"><span class="pre">Opponent</span></code></a><ul>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Opponent.name"><code class="docutils literal notranslate"><span class="pre">Opponent.name</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Opponent.title"><code class="docutils literal notranslate"><span class="pre">Opponent.title</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Opponent.rating"><code class="docutils literal notranslate"><span class="pre">Opponent.rating</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Opponent.is_engine"><code class="docutils literal notranslate"><span class="pre">Opponent.is_engine</span></code></a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#id1"><code class="docutils literal notranslate"><span class="pre">Protocol</span></code></a><ul>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Protocol.send_game_result"><code class="docutils literal notranslate"><span class="pre">Protocol.send_game_result()</span></code></a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#analysing-and-evaluating-a-position">Analysing and evaluating a position</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#id2"><code class="docutils literal notranslate"><span class="pre">Protocol</span></code></a><ul>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Protocol.analyse"><code class="docutils literal notranslate"><span class="pre">Protocol.analyse()</span></code></a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#chess.engine.InfoDict"><code class="docutils literal notranslate"><span class="pre">InfoDict</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#chess.engine.PovScore"><code class="docutils literal notranslate"><span class="pre">PovScore</span></code></a><ul>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.PovScore.relative"><code class="docutils literal notranslate"><span class="pre">PovScore.relative</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.PovScore.turn"><code class="docutils literal notranslate"><span class="pre">PovScore.turn</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.PovScore.white"><code class="docutils literal notranslate"><span class="pre">PovScore.white()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.PovScore.black"><code class="docutils literal notranslate"><span class="pre">PovScore.black()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.PovScore.pov"><code class="docutils literal notranslate"><span class="pre">PovScore.pov()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.PovScore.is_mate"><code class="docutils literal notranslate"><span class="pre">PovScore.is_mate()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.PovScore.wdl"><code class="docutils literal notranslate"><span class="pre">PovScore.wdl()</span></code></a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#chess.engine.Score"><code class="docutils literal notranslate"><span class="pre">Score</span></code></a><ul>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Score.score"><code class="docutils literal notranslate"><span class="pre">Score.score()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Score.mate"><code class="docutils literal notranslate"><span class="pre">Score.mate()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Score.is_mate"><code class="docutils literal notranslate"><span class="pre">Score.is_mate()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Score.wdl"><code class="docutils literal notranslate"><span class="pre">Score.wdl()</span></code></a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#chess.engine.PovWdl"><code class="docutils literal notranslate"><span class="pre">PovWdl</span></code></a><ul>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.PovWdl.relative"><code class="docutils literal notranslate"><span class="pre">PovWdl.relative</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.PovWdl.turn"><code class="docutils literal notranslate"><span class="pre">PovWdl.turn</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.PovWdl.white"><code class="docutils literal notranslate"><span class="pre">PovWdl.white()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.PovWdl.black"><code class="docutils literal notranslate"><span class="pre">PovWdl.black()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.PovWdl.pov"><code class="docutils literal notranslate"><span class="pre">PovWdl.pov()</span></code></a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#chess.engine.Wdl"><code class="docutils literal notranslate"><span class="pre">Wdl</span></code></a><ul>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Wdl.wins"><code class="docutils literal notranslate"><span class="pre">Wdl.wins</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Wdl.draws"><code class="docutils literal notranslate"><span class="pre">Wdl.draws</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Wdl.losses"><code class="docutils literal notranslate"><span class="pre">Wdl.losses</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Wdl.total"><code class="docutils literal notranslate"><span class="pre">Wdl.total()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Wdl.winning_chance"><code class="docutils literal notranslate"><span class="pre">Wdl.winning_chance()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Wdl.drawing_chance"><code class="docutils literal notranslate"><span class="pre">Wdl.drawing_chance()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Wdl.losing_chance"><code class="docutils literal notranslate"><span class="pre">Wdl.losing_chance()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Wdl.expectation"><code class="docutils literal notranslate"><span class="pre">Wdl.expectation()</span></code></a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#indefinite-or-infinite-analysis">Indefinite or infinite analysis</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#id3"><code class="docutils literal notranslate"><span class="pre">Protocol</span></code></a><ul>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Protocol.analysis"><code class="docutils literal notranslate"><span class="pre">Protocol.analysis()</span></code></a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#chess.engine.AnalysisResult"><code class="docutils literal notranslate"><span class="pre">AnalysisResult</span></code></a><ul>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.AnalysisResult.multipv"><code class="docutils literal notranslate"><span class="pre">AnalysisResult.multipv</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.AnalysisResult.info"><code class="docutils literal notranslate"><span class="pre">AnalysisResult.info</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.AnalysisResult.stop"><code class="docutils literal notranslate"><span class="pre">AnalysisResult.stop()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.AnalysisResult.wait"><code class="docutils literal notranslate"><span class="pre">AnalysisResult.wait()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.AnalysisResult.get"><code class="docutils literal notranslate"><span class="pre">AnalysisResult.get()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.AnalysisResult.would_block"><code class="docutils literal notranslate"><span class="pre">AnalysisResult.would_block()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.AnalysisResult.empty"><code class="docutils literal notranslate"><span class="pre">AnalysisResult.empty()</span></code></a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#chess.engine.BestMove"><code class="docutils literal notranslate"><span class="pre">BestMove</span></code></a><ul>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.BestMove.move"><code class="docutils literal notranslate"><span class="pre">BestMove.move</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.BestMove.ponder"><code class="docutils literal notranslate"><span class="pre">BestMove.ponder</span></code></a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#options">Options</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#id4"><code class="docutils literal notranslate"><span class="pre">Protocol</span></code></a><ul>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Protocol.options"><code class="docutils literal notranslate"><span class="pre">Protocol.options</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Protocol.configure"><code class="docutils literal notranslate"><span class="pre">Protocol.configure()</span></code></a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#chess.engine.Option"><code class="docutils literal notranslate"><span class="pre">Option</span></code></a><ul>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Option.name"><code class="docutils literal notranslate"><span class="pre">Option.name</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Option.type"><code class="docutils literal notranslate"><span class="pre">Option.type</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Option.default"><code class="docutils literal notranslate"><span class="pre">Option.default</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Option.min"><code class="docutils literal notranslate"><span class="pre">Option.min</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Option.max"><code class="docutils literal notranslate"><span class="pre">Option.max</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Option.var"><code class="docutils literal notranslate"><span class="pre">Option.var</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Option.is_managed"><code class="docutils literal notranslate"><span class="pre">Option.is_managed()</span></code></a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#logging">Logging</a></li>
<li class="toctree-l2"><a class="reference internal" href="#asyncssh">AsyncSSH</a></li>
<li class="toctree-l2"><a class="reference internal" href="#reference">Reference</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#chess.engine.EngineError"><code class="docutils literal notranslate"><span class="pre">EngineError</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#chess.engine.EngineTerminatedError"><code class="docutils literal notranslate"><span class="pre">EngineTerminatedError</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#chess.engine.AnalysisComplete"><code class="docutils literal notranslate"><span class="pre">AnalysisComplete</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#chess.engine.popen_uci"><code class="docutils literal notranslate"><span class="pre">popen_uci()</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#chess.engine.popen_xboard"><code class="docutils literal notranslate"><span class="pre">popen_xboard()</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#id7"><code class="docutils literal notranslate"><span class="pre">Protocol</span></code></a><ul>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Protocol.id"><code class="docutils literal notranslate"><span class="pre">Protocol.id</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Protocol.returncode"><code class="docutils literal notranslate"><span class="pre">Protocol.returncode</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Protocol.initialize"><code class="docutils literal notranslate"><span class="pre">Protocol.initialize()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Protocol.ping"><code class="docutils literal notranslate"><span class="pre">Protocol.ping()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.Protocol.quit"><code class="docutils literal notranslate"><span class="pre">Protocol.quit()</span></code></a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#chess.engine.UciProtocol"><code class="docutils literal notranslate"><span class="pre">UciProtocol</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#chess.engine.XBoardProtocol"><code class="docutils literal notranslate"><span class="pre">XBoardProtocol</span></code></a></li>
<li class="toctree-l3"><a class="reference internal" href="#chess.engine.SimpleEngine"><code class="docutils literal notranslate"><span class="pre">SimpleEngine</span></code></a><ul>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.SimpleEngine.close"><code class="docutils literal notranslate"><span class="pre">SimpleEngine.close()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.SimpleEngine.popen_uci"><code class="docutils literal notranslate"><span class="pre">SimpleEngine.popen_uci()</span></code></a></li>
<li class="toctree-l4"><a class="reference internal" href="#chess.engine.SimpleEngine.popen_xboard"><code class="docutils literal notranslate"><span class="pre">SimpleEngine.popen_xboard()</span></code></a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#chess.engine.SimpleAnalysisResult"><code class="docutils literal notranslate"><span class="pre">SimpleAnalysisResult</span></code></a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="svg.html">SVG rendering</a></li>
<li class="toctree-l1"><a class="reference internal" href="variant.html">Variants</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="changelog.html">Changelog for python-chess</a></li>
</ul>

        </div>
      </div>
    </nav>

    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
          <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
          <a href="index.html">python-chess</a>
      </nav>

      <div class="wy-nav-content">
        <div class="rst-content">
          <div role="navigation" aria-label="Page navigation">
  <ul class="wy-breadcrumbs">
      <li><a href="index.html" class="icon icon-home" aria-label="Home"></a></li>
      <li class="breadcrumb-item active">UCI/XBoard engine communication</li>
      <li class="wy-breadcrumbs-aside">
            <a href="_sources/engine.rst.txt" rel="nofollow"> View page source</a>
      </li>
  </ul>
  <hr/>
</div>
          <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
           <div itemprop="articleBody">
             
  <section id="uci-xboard-engine-communication">
<h1>UCI/XBoard engine communication<a class="headerlink" href="#uci-xboard-engine-communication" title="Link to this heading"></a></h1>
<p>The <a class="reference external" href="https://backscattering.de/chess/uci/">Universal chess interface (UCI)</a>
and <a class="reference external" href="https://www.gnu.org/software/xboard/engine-intf.html">XBoard protocol</a>
are standards for communicating with chess engines. This module
implements an abstraction for playing moves and analysing positions with
both kinds of engines.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>Many popular chess engines make no guarantees, not even memory
safety, when parameters and positions are not completely
<a class="reference internal" href="core.html#chess.Board.is_valid" title="chess.Board.is_valid"><code class="xref py py-func docutils literal notranslate"><span class="pre">valid</span></code></a>. This module tries to deal with
benign misbehaving engines, but ultimately they are executables running
on your system.</p>
</div>
<p>The preferred way to use the API is with an
<a class="reference external" href="https://docs.python.org/3/library/asyncio.html">asyncio</a> event loop.
The examples also show a synchronous wrapper
<a class="reference internal" href="#chess.engine.SimpleEngine" title="chess.engine.SimpleEngine"><code class="xref py py-class docutils literal notranslate"><span class="pre">SimpleEngine</span></code></a> that automatically spawns an event loop
in the background.
<a class="reference internal" href="#chess.engine.SimpleEngine" title="chess.engine.SimpleEngine"><code class="xref py py-class docutils literal notranslate"><span class="pre">SimpleEngine</span></code></a> methods block until there is a result.</p>
<section id="playing">
<h2>Playing<a class="headerlink" href="#playing" title="Link to this heading"></a></h2>
<p>Example: Let Stockfish play against itself, 100 milliseconds per move.</p>
<div class="literal-block-wrapper docutils container" id="id8">
<div class="code-block-caption"><span class="caption-text">Using synchronous <a class="reference internal" href="#chess.engine.SimpleEngine" title="chess.engine.SimpleEngine"><code class="xref py py-class docutils literal notranslate"><span class="pre">SimpleEngine</span></code></a></span><a class="headerlink" href="#id8" title="Link to this code"></a></div>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="kn">import</span><span class="w"> </span><span class="nn">chess</span>
 <span class="kn">import</span><span class="w"> </span><span class="nn">chess.engine</span>

 <span class="n">engine</span> <span class="o">=</span> <span class="n">chess</span><span class="o">.</span><span class="n">engine</span><span class="o">.</span><span class="n">SimpleEngine</span><span class="o">.</span><span class="n">popen_uci</span><span class="p">(</span><span class="sa">r</span><span class="s2">&quot;C:\Users\xxxxx\Downloads\stockfish_14_win_x64\stockfish_14_win_x64_avx2.exe&quot;</span><span class="p">)</span>

 <span class="n">board</span> <span class="o">=</span> <span class="n">chess</span><span class="o">.</span><span class="n">Board</span><span class="p">()</span>
 <span class="k">while</span> <span class="ow">not</span> <span class="n">board</span><span class="o">.</span><span class="n">is_game_over</span><span class="p">():</span>
     <span class="n">result</span> <span class="o">=</span> <span class="n">engine</span><span class="o">.</span><span class="n">play</span><span class="p">(</span><span class="n">board</span><span class="p">,</span> <span class="n">chess</span><span class="o">.</span><span class="n">engine</span><span class="o">.</span><span class="n">Limit</span><span class="p">(</span><span class="n">time</span><span class="o">=</span><span class="mf">0.1</span><span class="p">))</span>
     <span class="n">board</span><span class="o">.</span><span class="n">push</span><span class="p">(</span><span class="n">result</span><span class="o">.</span><span class="n">move</span><span class="p">)</span>

 <span class="n">engine</span><span class="o">.</span><span class="n">quit</span><span class="p">()</span>
</pre></div>
</div>
</div>
<div class="literal-block-wrapper docutils container" id="id9">
<div class="code-block-caption"><span class="caption-text">Using asyncio</span><a class="headerlink" href="#id9" title="Link to this code"></a></div>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="kn">import</span><span class="w"> </span><span class="nn">asyncio</span>
 <span class="kn">import</span><span class="w"> </span><span class="nn">chess</span>
 <span class="kn">import</span><span class="w"> </span><span class="nn">chess.engine</span>

 <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="kc">None</span><span class="p">:</span>
     <span class="n">transport</span><span class="p">,</span> <span class="n">engine</span> <span class="o">=</span> <span class="k">await</span> <span class="n">chess</span><span class="o">.</span><span class="n">engine</span><span class="o">.</span><span class="n">popen_uci</span><span class="p">(</span><span class="sa">r</span><span class="s2">&quot;C:\Users\xxxxx\Downloads\stockfish_14_win_x64\stockfish_14_win_x64_avx2.exe&quot;</span><span class="p">)</span>

     <span class="n">board</span> <span class="o">=</span> <span class="n">chess</span><span class="o">.</span><span class="n">Board</span><span class="p">()</span>
     <span class="k">while</span> <span class="ow">not</span> <span class="n">board</span><span class="o">.</span><span class="n">is_game_over</span><span class="p">():</span>
         <span class="n">result</span> <span class="o">=</span> <span class="k">await</span> <span class="n">engine</span><span class="o">.</span><span class="n">play</span><span class="p">(</span><span class="n">board</span><span class="p">,</span> <span class="n">chess</span><span class="o">.</span><span class="n">engine</span><span class="o">.</span><span class="n">Limit</span><span class="p">(</span><span class="n">time</span><span class="o">=</span><span class="mf">0.1</span><span class="p">))</span>
         <span class="n">board</span><span class="o">.</span><span class="n">push</span><span class="p">(</span><span class="n">result</span><span class="o">.</span><span class="n">move</span><span class="p">)</span>

     <span class="k">await</span> <span class="n">engine</span><span class="o">.</span><span class="n">quit</span><span class="p">()</span>

 <span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">())</span>
</pre></div>
</div>
</div>
<dl class="py class">
<dt class="sig sig-object py" id="chess.engine.Protocol">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">chess.engine.</span></span><span class="sig-name descname"><span class="pre">Protocol</span></span><a class="reference internal" href="_modules/chess/engine.html#Protocol"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.Protocol" title="Link to this definition"></a></dt>
<dd><p>Protocol for communicating with a chess engine process.</p>
<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.Protocol.play">
<em class="property"><span class="pre">abstract</span><span class="w"> </span><span class="pre">async</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">play</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">board:</span> <span class="pre">~chess.Board</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">limit:</span> <span class="pre">~chess.engine.Limit</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">game:</span> <span class="pre">object</span> <span class="pre">|</span> <span class="pre">None</span> <span class="pre">=</span> <span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">info:</span> <span class="pre">~chess.engine.Info</span> <span class="pre">=</span> <span class="pre">&lt;Info.NONE:</span> <span class="pre">0&gt;</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">ponder:</span> <span class="pre">bool</span> <span class="pre">=</span> <span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">draw_offered:</span> <span class="pre">bool</span> <span class="pre">=</span> <span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">root_moves:</span> <span class="pre">~typing.Iterable[~chess.Move]</span> <span class="pre">|</span> <span class="pre">None</span> <span class="pre">=</span> <span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">options:</span> <span class="pre">~typing.Mapping[str</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">str</span> <span class="pre">|</span> <span class="pre">int</span> <span class="pre">|</span> <span class="pre">bool</span> <span class="pre">|</span> <span class="pre">None]</span> <span class="pre">=</span> <span class="pre">{}</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">opponent:</span> <span class="pre">~chess.engine.Opponent</span> <span class="pre">|</span> <span class="pre">None</span> <span class="pre">=</span> <span class="pre">None</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference internal" href="#chess.engine.PlayResult" title="chess.engine.PlayResult"><span class="pre">PlayResult</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#Protocol.play"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.Protocol.play" title="Link to this definition"></a></dt>
<dd><p>Plays a position.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>board</strong> – The position. The entire move stack will be sent to the
engine.</p></li>
<li><p><strong>limit</strong> – An instance of <a class="reference internal" href="#chess.engine.Limit" title="chess.engine.Limit"><code class="xref py py-class docutils literal notranslate"><span class="pre">chess.engine.Limit</span></code></a> that
determines when to stop thinking.</p></li>
<li><p><strong>game</strong> – Optional. An arbitrary object that identifies the game.
Will automatically inform the engine if the object is not equal
to the previous game (e.g., <code class="docutils literal notranslate"><span class="pre">ucinewgame</span></code>, <code class="docutils literal notranslate"><span class="pre">new</span></code>).</p></li>
<li><p><strong>info</strong> – Selects which additional information to retrieve from the
engine. <code class="docutils literal notranslate"><span class="pre">INFO_NONE</span></code>, <code class="docutils literal notranslate"><span class="pre">INFO_BASIC</span></code> (basic information that is
trivial to obtain), <code class="docutils literal notranslate"><span class="pre">INFO_SCORE</span></code>, <code class="docutils literal notranslate"><span class="pre">INFO_PV</span></code>,
<code class="docutils literal notranslate"><span class="pre">INFO_REFUTATION</span></code>, <code class="docutils literal notranslate"><span class="pre">INFO_CURRLINE</span></code>, <code class="docutils literal notranslate"><span class="pre">INFO_ALL</span></code> or any
bitwise combination. Some overhead is associated with parsing
extra information.</p></li>
<li><p><strong>ponder</strong> – Whether the engine should keep analysing in the
background even after the result has been returned.</p></li>
<li><p><strong>draw_offered</strong> – Whether the engine’s opponent has offered a draw.
Ignored by UCI engines.</p></li>
<li><p><strong>root_moves</strong> – Optional. Consider only root moves from this list.</p></li>
<li><p><strong>options</strong> – Optional. A dictionary of engine options for the
analysis. The previous configuration will be restored after the
analysis is complete. You can permanently apply a configuration
with <a class="reference internal" href="#chess.engine.Protocol.configure" title="chess.engine.Protocol.configure"><code class="xref py py-func docutils literal notranslate"><span class="pre">configure()</span></code></a>.</p></li>
<li><p><strong>opponent</strong> – Optional. Information about a new opponent. Information
about the original opponent will be restored once the move is
complete. New opponent information can be made permanent with
<a class="reference internal" href="#chess.engine.Protocol.send_opponent_information" title="chess.engine.Protocol.send_opponent_information"><code class="xref py py-func docutils literal notranslate"><span class="pre">send_opponent_information()</span></code></a>.</p></li>
</ul>
</dd>
</dl>
</dd></dl>

</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="chess.engine.Limit">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">chess.engine.</span></span><span class="sig-name descname"><span class="pre">Limit</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">time</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><span class="pre">float</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">depth</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">nodes</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">mate</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">white_clock</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><span class="pre">float</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">black_clock</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><span class="pre">float</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">white_inc</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><span class="pre">float</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">black_inc</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><span class="pre">float</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">remaining_moves</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">clock_id</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#object" title="(in Python v3.13)"><span class="pre">object</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/chess/engine.html#Limit"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.Limit" title="Link to this definition"></a></dt>
<dd><p>Search-termination condition.</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.Limit.time">
<span class="sig-name descname"><span class="pre">time</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><span class="pre">float</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></em><em class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">None</span></em><a class="headerlink" href="#chess.engine.Limit.time" title="Link to this definition"></a></dt>
<dd><p>Search exactly <em>time</em> seconds.</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.Limit.depth">
<span class="sig-name descname"><span class="pre">depth</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></em><em class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">None</span></em><a class="headerlink" href="#chess.engine.Limit.depth" title="Link to this definition"></a></dt>
<dd><p>Search <em>depth</em> ply only.</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.Limit.nodes">
<span class="sig-name descname"><span class="pre">nodes</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></em><em class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">None</span></em><a class="headerlink" href="#chess.engine.Limit.nodes" title="Link to this definition"></a></dt>
<dd><p>Search only a limited number of <em>nodes</em>.</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.Limit.mate">
<span class="sig-name descname"><span class="pre">mate</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></em><em class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">None</span></em><a class="headerlink" href="#chess.engine.Limit.mate" title="Link to this definition"></a></dt>
<dd><p>Search for a mate in <em>mate</em> moves.</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.Limit.white_clock">
<span class="sig-name descname"><span class="pre">white_clock</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><span class="pre">float</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></em><em class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">None</span></em><a class="headerlink" href="#chess.engine.Limit.white_clock" title="Link to this definition"></a></dt>
<dd><p>Time in seconds remaining for White.</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.Limit.black_clock">
<span class="sig-name descname"><span class="pre">black_clock</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><span class="pre">float</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></em><em class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">None</span></em><a class="headerlink" href="#chess.engine.Limit.black_clock" title="Link to this definition"></a></dt>
<dd><p>Time in seconds remaining for Black.</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.Limit.white_inc">
<span class="sig-name descname"><span class="pre">white_inc</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><span class="pre">float</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></em><em class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">None</span></em><a class="headerlink" href="#chess.engine.Limit.white_inc" title="Link to this definition"></a></dt>
<dd><p>Fisher increment for White, in seconds.</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.Limit.black_inc">
<span class="sig-name descname"><span class="pre">black_inc</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><span class="pre">float</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></em><em class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">None</span></em><a class="headerlink" href="#chess.engine.Limit.black_inc" title="Link to this definition"></a></dt>
<dd><p>Fisher increment for Black, in seconds.</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.Limit.remaining_moves">
<span class="sig-name descname"><span class="pre">remaining_moves</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></em><em class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">None</span></em><a class="headerlink" href="#chess.engine.Limit.remaining_moves" title="Link to this definition"></a></dt>
<dd><p>Number of moves to the next time control. If this is not set, but
<em>white_clock</em> and <em>black_clock</em> are, then it is sudden death.</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.Limit.clock_id">
<span class="sig-name descname"><span class="pre">clock_id</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#object" title="(in Python v3.13)"><span class="pre">object</span></a></em><em class="property"><span class="w"> </span><span class="p"><span class="pre">=</span></span><span class="w"> </span><span class="pre">None</span></em><a class="headerlink" href="#chess.engine.Limit.clock_id" title="Link to this definition"></a></dt>
<dd><p>An identifier to use with XBoard engines to signal that the time
control has changed. When this field changes, Xboard engines are
sent level or st commands as appropriate. Otherwise, only time
and otim commands are sent to update the engine’s clock.</p>
</dd></dl>

</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="chess.engine.PlayResult">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">chess.engine.</span></span><span class="sig-name descname"><span class="pre">PlayResult</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">move</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="core.html#chess.Move" title="chess.Move"><span class="pre">Move</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">ponder</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="core.html#chess.Move" title="chess.Move"><span class="pre">Move</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">info</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="#chess.engine.InfoDict" title="chess.engine.InfoDict"><span class="pre">InfoDict</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">draw_offered</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><span class="pre">bool</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">resigned</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><span class="pre">bool</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/chess/engine.html#PlayResult"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.PlayResult" title="Link to this definition"></a></dt>
<dd><p>Returned by <a class="reference internal" href="#chess.engine.Protocol.play" title="chess.engine.Protocol.play"><code class="xref py py-func docutils literal notranslate"><span class="pre">chess.engine.Protocol.play()</span></code></a>.</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.PlayResult.move">
<span class="sig-name descname"><span class="pre">move</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference internal" href="core.html#chess.Move" title="chess.Move"><span class="pre">Move</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></em><a class="headerlink" href="#chess.engine.PlayResult.move" title="Link to this definition"></a></dt>
<dd><p>The best move according to the engine, or <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.PlayResult.ponder">
<span class="sig-name descname"><span class="pre">ponder</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference internal" href="core.html#chess.Move" title="chess.Move"><span class="pre">Move</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></em><a class="headerlink" href="#chess.engine.PlayResult.ponder" title="Link to this definition"></a></dt>
<dd><p>The response that the engine expects after <em>move</em>, or <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.PlayResult.info">
<span class="sig-name descname"><span class="pre">info</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference internal" href="#chess.engine.InfoDict" title="chess.engine.InfoDict"><span class="pre">InfoDict</span></a></em><a class="headerlink" href="#chess.engine.PlayResult.info" title="Link to this definition"></a></dt>
<dd><p>A dictionary of extra <a class="reference internal" href="#chess.engine.InfoDict" title="chess.engine.InfoDict"><code class="xref py py-class docutils literal notranslate"><span class="pre">information</span></code></a>
sent by the engine, if selected with the <em>info</em> argument of
<a class="reference internal" href="#chess.engine.Protocol.play" title="chess.engine.Protocol.play"><code class="xref py py-func docutils literal notranslate"><span class="pre">play()</span></code></a>.</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.PlayResult.draw_offered">
<span class="sig-name descname"><span class="pre">draw_offered</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><span class="pre">bool</span></a></em><a class="headerlink" href="#chess.engine.PlayResult.draw_offered" title="Link to this definition"></a></dt>
<dd><p>Whether the engine offered a draw before moving.</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.PlayResult.resigned">
<span class="sig-name descname"><span class="pre">resigned</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><span class="pre">bool</span></a></em><a class="headerlink" href="#chess.engine.PlayResult.resigned" title="Link to this definition"></a></dt>
<dd><p>Whether the engine resigned.</p>
</dd></dl>

</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="id0">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">chess.engine.</span></span><span class="sig-name descname"><span class="pre">Protocol</span></span><a class="reference internal" href="_modules/chess/engine.html#Protocol"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#id0" title="Link to this definition"></a></dt>
<dd><p>Protocol for communicating with a chess engine process.</p>
<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.Protocol.send_opponent_information">
<em class="property"><span class="pre">abstract</span><span class="w"> </span><span class="pre">async</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">send_opponent_information</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">opponent</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="#chess.engine.Opponent" title="chess.engine.Opponent"><span class="pre">Opponent</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">engine_rating</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#Protocol.send_opponent_information"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.Protocol.send_opponent_information" title="Link to this definition"></a></dt>
<dd><p>Sends the engine information about its opponent. The information will
be sent after a new game is announced and before the first move. This
method should be called before the first move of a game–i.e., the
first call to <a class="reference internal" href="#chess.engine.Protocol.play" title="chess.engine.Protocol.play"><code class="xref py py-func docutils literal notranslate"><span class="pre">chess.engine.Protocol.play()</span></code></a>.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>opponent</strong> – Optional. An instance of <a class="reference internal" href="#chess.engine.Opponent" title="chess.engine.Opponent"><code class="xref py py-class docutils literal notranslate"><span class="pre">chess.engine.Opponent</span></code></a> that has the opponent’s information.</p></li>
<li><p><strong>engine_rating</strong> – Optional. This engine’s own rating. Only used by XBoard engines.</p></li>
</ul>
</dd>
</dl>
</dd></dl>

</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="chess.engine.Opponent">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">chess.engine.</span></span><span class="sig-name descname"><span class="pre">Opponent</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.13)"><span class="pre">str</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">title</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.13)"><span class="pre">str</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">rating</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">is_engine</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><span class="pre">bool</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/chess/engine.html#Opponent"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.Opponent" title="Link to this definition"></a></dt>
<dd><p>Used to store information about an engine’s opponent.</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.Opponent.name">
<span class="sig-name descname"><span class="pre">name</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.13)"><span class="pre">str</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></em><a class="headerlink" href="#chess.engine.Opponent.name" title="Link to this definition"></a></dt>
<dd><p>The name of the opponent.</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.Opponent.title">
<span class="sig-name descname"><span class="pre">title</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.13)"><span class="pre">str</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></em><a class="headerlink" href="#chess.engine.Opponent.title" title="Link to this definition"></a></dt>
<dd><p>The opponent’s title–for example, GM, IM, or BOT.</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.Opponent.rating">
<span class="sig-name descname"><span class="pre">rating</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></em><a class="headerlink" href="#chess.engine.Opponent.rating" title="Link to this definition"></a></dt>
<dd><p>The opponent’s ELO rating.</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.Opponent.is_engine">
<span class="sig-name descname"><span class="pre">is_engine</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><span class="pre">bool</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></em><a class="headerlink" href="#chess.engine.Opponent.is_engine" title="Link to this definition"></a></dt>
<dd><p>Whether the opponent is a chess engine/computer program.</p>
</dd></dl>

</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="id1">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">chess.engine.</span></span><span class="sig-name descname"><span class="pre">Protocol</span></span><a class="reference internal" href="_modules/chess/engine.html#Protocol"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#id1" title="Link to this definition"></a></dt>
<dd><p>Protocol for communicating with a chess engine process.</p>
<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.Protocol.send_game_result">
<em class="property"><span class="pre">abstract</span><span class="w"> </span><span class="pre">async</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">send_game_result</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">board</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="core.html#chess.Board" title="chess.Board"><span class="pre">Board</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">winner</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">chess.Color</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">game_ending</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.13)"><span class="pre">str</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">game_complete</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><span class="pre">bool</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#Protocol.send_game_result"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.Protocol.send_game_result" title="Link to this definition"></a></dt>
<dd><p>Sends the engine the result of the game.</p>
<p>XBoard engines receive the final moves and a line of the form
<code class="docutils literal notranslate"><span class="pre">result</span> <span class="pre">&lt;winner&gt;</span> <span class="pre">{&lt;ending&gt;}</span></code>. The <code class="docutils literal notranslate"><span class="pre">&lt;winner&gt;</span></code> field is one of <code class="docutils literal notranslate"><span class="pre">1-0</span></code>,
<code class="docutils literal notranslate"><span class="pre">0-1</span></code>, <code class="docutils literal notranslate"><span class="pre">1/2-1/2</span></code>, or <code class="docutils literal notranslate"><span class="pre">*</span></code> to indicate white won, black won, draw,
or adjournment, respectively. The <code class="docutils literal notranslate"><span class="pre">&lt;ending&gt;</span></code> field is a description
of the specific reason for the end of the game: “White mates”,
“Time forfeiture”, “Stalemate”, etc.</p>
<p>UCI engines do not expect end-of-game information and so are not
sent anything.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>board</strong> – The final state of the board.</p></li>
<li><p><strong>winner</strong> – Optional. Specify the winner of the game. This is useful
if the result of the game is not evident from the board–e.g., time
forfeiture or draw by agreement. If not <code class="docutils literal notranslate"><span class="pre">None</span></code>, this parameter
overrides any winner derivable from the board.</p></li>
<li><p><strong>game_ending</strong> – Optional. Text describing the reason for the game
ending. Similarly to the winner parameter, this overrides any game
result derivable from the board.</p></li>
<li><p><strong>game_complete</strong> – Optional. Whether the game reached completion.</p></li>
</ul>
</dd>
</dl>
</dd></dl>

</dd></dl>

</section>
<section id="analysing-and-evaluating-a-position">
<h2>Analysing and evaluating a position<a class="headerlink" href="#analysing-and-evaluating-a-position" title="Link to this heading"></a></h2>
<p>Example:</p>
<div class="literal-block-wrapper docutils container" id="id10">
<div class="code-block-caption"><span class="caption-text">Using synchronous <a class="reference internal" href="#chess.engine.SimpleEngine" title="chess.engine.SimpleEngine"><code class="xref py py-class docutils literal notranslate"><span class="pre">SimpleEngine</span></code></a></span><a class="headerlink" href="#id10" title="Link to this code"></a></div>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="kn">import</span><span class="w"> </span><span class="nn">chess</span>
 <span class="kn">import</span><span class="w"> </span><span class="nn">chess.engine</span>

 <span class="n">engine</span> <span class="o">=</span> <span class="n">chess</span><span class="o">.</span><span class="n">engine</span><span class="o">.</span><span class="n">SimpleEngine</span><span class="o">.</span><span class="n">popen_uci</span><span class="p">(</span><span class="s2">&quot;/usr/bin/stockfish&quot;</span><span class="p">)</span>

 <span class="n">board</span> <span class="o">=</span> <span class="n">chess</span><span class="o">.</span><span class="n">Board</span><span class="p">()</span>
 <span class="n">info</span> <span class="o">=</span> <span class="n">engine</span><span class="o">.</span><span class="n">analyse</span><span class="p">(</span><span class="n">board</span><span class="p">,</span> <span class="n">chess</span><span class="o">.</span><span class="n">engine</span><span class="o">.</span><span class="n">Limit</span><span class="p">(</span><span class="n">time</span><span class="o">=</span><span class="mf">0.1</span><span class="p">))</span>
 <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Score:&quot;</span><span class="p">,</span> <span class="n">info</span><span class="p">[</span><span class="s2">&quot;score&quot;</span><span class="p">])</span>
 <span class="c1"># Score: PovScore(Cp(+20), WHITE)</span>

 <span class="n">board</span> <span class="o">=</span> <span class="n">chess</span><span class="o">.</span><span class="n">Board</span><span class="p">(</span><span class="s2">&quot;r1bqkbnr/p1pp1ppp/1pn5/4p3/2B1P3/5Q2/PPPP1PPP/RNB1K1NR w KQkq - 2 4&quot;</span><span class="p">)</span>
 <span class="n">info</span> <span class="o">=</span> <span class="n">engine</span><span class="o">.</span><span class="n">analyse</span><span class="p">(</span><span class="n">board</span><span class="p">,</span> <span class="n">chess</span><span class="o">.</span><span class="n">engine</span><span class="o">.</span><span class="n">Limit</span><span class="p">(</span><span class="n">depth</span><span class="o">=</span><span class="mi">20</span><span class="p">))</span>
 <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;Score:&quot;</span><span class="p">,</span> <span class="n">info</span><span class="p">[</span><span class="s2">&quot;score&quot;</span><span class="p">])</span>
 <span class="c1"># Score: PovScore(Mate(+1), WHITE)</span>

 <span class="n">engine</span><span class="o">.</span><span class="n">quit</span><span class="p">()</span>
</pre></div>
</div>
</div>
<div class="literal-block-wrapper docutils container" id="id11">
<div class="code-block-caption"><span class="caption-text">Using asyncio</span><a class="headerlink" href="#id11" title="Link to this code"></a></div>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="kn">import</span><span class="w"> </span><span class="nn">asyncio</span>
 <span class="kn">import</span><span class="w"> </span><span class="nn">chess</span>
 <span class="kn">import</span><span class="w"> </span><span class="nn">chess.engine</span>

 <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="kc">None</span><span class="p">:</span>
     <span class="n">transport</span><span class="p">,</span> <span class="n">engine</span> <span class="o">=</span> <span class="k">await</span> <span class="n">chess</span><span class="o">.</span><span class="n">engine</span><span class="o">.</span><span class="n">popen_uci</span><span class="p">(</span><span class="s2">&quot;/usr/bin/stockfish&quot;</span><span class="p">)</span>

     <span class="n">board</span> <span class="o">=</span> <span class="n">chess</span><span class="o">.</span><span class="n">Board</span><span class="p">()</span>
     <span class="n">info</span> <span class="o">=</span> <span class="k">await</span> <span class="n">engine</span><span class="o">.</span><span class="n">analyse</span><span class="p">(</span><span class="n">board</span><span class="p">,</span> <span class="n">chess</span><span class="o">.</span><span class="n">engine</span><span class="o">.</span><span class="n">Limit</span><span class="p">(</span><span class="n">time</span><span class="o">=</span><span class="mf">0.1</span><span class="p">))</span>
     <span class="nb">print</span><span class="p">(</span><span class="n">info</span><span class="p">[</span><span class="s2">&quot;score&quot;</span><span class="p">])</span>
     <span class="c1"># Score: PovScore(Cp(+20), WHITE)</span>

     <span class="n">board</span> <span class="o">=</span> <span class="n">chess</span><span class="o">.</span><span class="n">Board</span><span class="p">(</span><span class="s2">&quot;r1bqkbnr/p1pp1ppp/1pn5/4p3/2B1P3/5Q2/PPPP1PPP/RNB1K1NR w KQkq - 2 4&quot;</span><span class="p">)</span>
     <span class="n">info</span> <span class="o">=</span> <span class="k">await</span> <span class="n">engine</span><span class="o">.</span><span class="n">analyse</span><span class="p">(</span><span class="n">board</span><span class="p">,</span> <span class="n">chess</span><span class="o">.</span><span class="n">engine</span><span class="o">.</span><span class="n">Limit</span><span class="p">(</span><span class="n">depth</span><span class="o">=</span><span class="mi">20</span><span class="p">))</span>
     <span class="nb">print</span><span class="p">(</span><span class="n">info</span><span class="p">[</span><span class="s2">&quot;score&quot;</span><span class="p">])</span>
     <span class="c1"># Score: PovScore(Mate(+1), WHITE)</span>

     <span class="k">await</span> <span class="n">engine</span><span class="o">.</span><span class="n">quit</span><span class="p">()</span>

 <span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">())</span>
</pre></div>
</div>
</div>
<dl class="py class">
<dt class="sig sig-object py" id="id2">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">chess.engine.</span></span><span class="sig-name descname"><span class="pre">Protocol</span></span><a class="reference internal" href="_modules/chess/engine.html#Protocol"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#id2" title="Link to this definition"></a></dt>
<dd><p>Protocol for communicating with a chess engine process.</p>
<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.Protocol.analyse">
<em class="property"><span class="pre">async</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">analyse</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">board</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="core.html#chess.Board" title="chess.Board"><span class="pre">Board</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">limit</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="#chess.engine.Limit" title="chess.engine.Limit"><span class="pre">Limit</span></a></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">game</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#object" title="(in Python v3.13)"><span class="pre">object</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">info</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Info</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">INFO_ALL</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">root_moves</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.Iterable" title="(in Python v3.13)"><span class="pre">Iterable</span></a><span class="p"><span class="pre">[</span></span><a class="reference internal" href="core.html#chess.Move" title="chess.Move"><span class="pre">Move</span></a><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">options</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.Mapping" title="(in Python v3.13)"><span class="pre">Mapping</span></a><span class="p"><span class="pre">[</span></span><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.13)"><span class="pre">str</span></a><span class="p"><span class="pre">,</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.13)"><span class="pre">str</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><span class="pre">bool</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a><span class="p"><span class="pre">]</span></span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">{}</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference internal" href="#chess.engine.InfoDict" title="chess.engine.InfoDict"><span class="pre">InfoDict</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#Protocol.analyse"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.Protocol.analyse" title="Link to this definition"></a></dt>
<dt class="sig sig-object py">
<em class="property"><span class="pre">async</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">analyse</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">board</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="core.html#chess.Board" title="chess.Board"><span class="pre">Board</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">limit</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="#chess.engine.Limit" title="chess.engine.Limit"><span class="pre">Limit</span></a></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">multipv</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">game</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#object" title="(in Python v3.13)"><span class="pre">object</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">info</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Info</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">INFO_ALL</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">root_moves</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.Iterable" title="(in Python v3.13)"><span class="pre">Iterable</span></a><span class="p"><span class="pre">[</span></span><a class="reference internal" href="core.html#chess.Move" title="chess.Move"><span class="pre">Move</span></a><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">options</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.Mapping" title="(in Python v3.13)"><span class="pre">Mapping</span></a><span class="p"><span class="pre">[</span></span><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.13)"><span class="pre">str</span></a><span class="p"><span class="pre">,</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.13)"><span class="pre">str</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><span class="pre">bool</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a><span class="p"><span class="pre">]</span></span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">{}</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.List" title="(in Python v3.13)"><span class="pre">List</span></a><span class="p"><span class="pre">[</span></span><a class="reference internal" href="#chess.engine.InfoDict" title="chess.engine.InfoDict"><span class="pre">InfoDict</span></a><span class="p"><span class="pre">]</span></span></span></span></dt>
<dt class="sig sig-object py">
<em class="property"><span class="pre">async</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">analyse</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">board</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="core.html#chess.Board" title="chess.Board"><span class="pre">Board</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">limit</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="#chess.engine.Limit" title="chess.engine.Limit"><span class="pre">Limit</span></a></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">multipv</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">game</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#object" title="(in Python v3.13)"><span class="pre">object</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">info</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Info</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">INFO_ALL</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">root_moves</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.Iterable" title="(in Python v3.13)"><span class="pre">Iterable</span></a><span class="p"><span class="pre">[</span></span><a class="reference internal" href="core.html#chess.Move" title="chess.Move"><span class="pre">Move</span></a><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">options</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.Mapping" title="(in Python v3.13)"><span class="pre">Mapping</span></a><span class="p"><span class="pre">[</span></span><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.13)"><span class="pre">str</span></a><span class="p"><span class="pre">,</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.13)"><span class="pre">str</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><span class="pre">bool</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a><span class="p"><span class="pre">]</span></span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">{}</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.List" title="(in Python v3.13)"><span class="pre">List</span></a><span class="p"><span class="pre">[</span></span><a class="reference internal" href="#chess.engine.InfoDict" title="chess.engine.InfoDict"><span class="pre">InfoDict</span></a><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference internal" href="#chess.engine.InfoDict" title="chess.engine.InfoDict"><span class="pre">InfoDict</span></a></span></span></dt>
<dd><p>Analyses a position and returns a dictionary of
<a class="reference internal" href="#chess.engine.InfoDict" title="chess.engine.InfoDict"><code class="xref py py-class docutils literal notranslate"><span class="pre">information</span></code></a>.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>board</strong> – The position to analyse. The entire move stack will be
sent to the engine.</p></li>
<li><p><strong>limit</strong> – An instance of <a class="reference internal" href="#chess.engine.Limit" title="chess.engine.Limit"><code class="xref py py-class docutils literal notranslate"><span class="pre">chess.engine.Limit</span></code></a> that
determines when to stop the analysis.</p></li>
<li><p><strong>multipv</strong> – Optional. Analyse multiple root moves. Will return
a list of at most <em>multipv</em> dictionaries rather than just a single
info dictionary.</p></li>
<li><p><strong>game</strong> – Optional. An arbitrary object that identifies the game.
Will automatically inform the engine if the object is not equal
to the previous game (e.g., <code class="docutils literal notranslate"><span class="pre">ucinewgame</span></code>, <code class="docutils literal notranslate"><span class="pre">new</span></code>).</p></li>
<li><p><strong>info</strong> – Selects which information to retrieve from the
engine. <code class="docutils literal notranslate"><span class="pre">INFO_NONE</span></code>, <code class="docutils literal notranslate"><span class="pre">INFO_BASIC</span></code> (basic information that is
trivial to obtain), <code class="docutils literal notranslate"><span class="pre">INFO_SCORE</span></code>, <code class="docutils literal notranslate"><span class="pre">INFO_PV</span></code>,
<code class="docutils literal notranslate"><span class="pre">INFO_REFUTATION</span></code>, <code class="docutils literal notranslate"><span class="pre">INFO_CURRLINE</span></code>, <code class="docutils literal notranslate"><span class="pre">INFO_ALL</span></code> or any
bitwise combination. Some overhead is associated with parsing
extra information.</p></li>
<li><p><strong>root_moves</strong> – Optional. Limit analysis to a list of root moves.</p></li>
<li><p><strong>options</strong> – Optional. A dictionary of engine options for the
analysis. The previous configuration will be restored after the
analysis is complete. You can permanently apply a configuration
with <a class="reference internal" href="#chess.engine.Protocol.configure" title="chess.engine.Protocol.configure"><code class="xref py py-func docutils literal notranslate"><span class="pre">configure()</span></code></a>.</p></li>
</ul>
</dd>
</dl>
</dd></dl>

</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="chess.engine.InfoDict">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">chess.engine.</span></span><span class="sig-name descname"><span class="pre">InfoDict</span></span><a class="reference internal" href="_modules/chess/engine.html#InfoDict"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.InfoDict" title="Link to this definition"></a></dt>
<dd><p>Dictionary of aggregated information sent by the engine.</p>
<p>Commonly used keys are: <code class="docutils literal notranslate"><span class="pre">score</span></code> (a <a class="reference internal" href="#chess.engine.PovScore" title="chess.engine.PovScore"><code class="xref py py-class docutils literal notranslate"><span class="pre">PovScore</span></code></a>),
<code class="docutils literal notranslate"><span class="pre">pv</span></code> (a list of <a class="reference internal" href="core.html#chess.Move" title="chess.Move"><code class="xref py py-class docutils literal notranslate"><span class="pre">Move</span></code></a> objects), <code class="docutils literal notranslate"><span class="pre">depth</span></code>,
<code class="docutils literal notranslate"><span class="pre">seldepth</span></code>, <code class="docutils literal notranslate"><span class="pre">time</span></code> (in seconds), <code class="docutils literal notranslate"><span class="pre">nodes</span></code>, <code class="docutils literal notranslate"><span class="pre">nps</span></code>, <code class="docutils literal notranslate"><span class="pre">multipv</span></code>
(<code class="docutils literal notranslate"><span class="pre">1</span></code> for the mainline).</p>
<p>Others: <code class="docutils literal notranslate"><span class="pre">tbhits</span></code>, <code class="docutils literal notranslate"><span class="pre">currmove</span></code>, <code class="docutils literal notranslate"><span class="pre">currmovenumber</span></code>, <code class="docutils literal notranslate"><span class="pre">hashfull</span></code>,
<code class="docutils literal notranslate"><span class="pre">cpuload</span></code>, <code class="docutils literal notranslate"><span class="pre">refutation</span></code>, <code class="docutils literal notranslate"><span class="pre">currline</span></code>, <code class="docutils literal notranslate"><span class="pre">ebf</span></code> (effective branching factor),
<code class="docutils literal notranslate"><span class="pre">wdl</span></code> (a <a class="reference internal" href="#chess.engine.PovWdl" title="chess.engine.PovWdl"><code class="xref py py-class docutils literal notranslate"><span class="pre">PovWdl</span></code></a>), and <code class="docutils literal notranslate"><span class="pre">string</span></code>.</p>
</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="chess.engine.PovScore">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">chess.engine.</span></span><span class="sig-name descname"><span class="pre">PovScore</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">relative</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="#chess.engine.Score" title="chess.engine.Score"><span class="pre">Score</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">turn</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">chess.Color</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/chess/engine.html#PovScore"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.PovScore" title="Link to this definition"></a></dt>
<dd><p>A relative <a class="reference internal" href="#chess.engine.Score" title="chess.engine.Score"><code class="xref py py-class docutils literal notranslate"><span class="pre">Score</span></code></a> and the point of view.</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.PovScore.relative">
<span class="sig-name descname"><span class="pre">relative</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference internal" href="#chess.engine.Score" title="chess.engine.Score"><span class="pre">Score</span></a></em><a class="headerlink" href="#chess.engine.PovScore.relative" title="Link to this definition"></a></dt>
<dd><p>The relative <a class="reference internal" href="#chess.engine.Score" title="chess.engine.Score"><code class="xref py py-class docutils literal notranslate"><span class="pre">Score</span></code></a>.</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.PovScore.turn">
<span class="sig-name descname"><span class="pre">turn</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><span class="pre">bool</span></a></em><a class="headerlink" href="#chess.engine.PovScore.turn" title="Link to this definition"></a></dt>
<dd><p>The point of view (<code class="docutils literal notranslate"><span class="pre">chess.WHITE</span></code> or <code class="docutils literal notranslate"><span class="pre">chess.BLACK</span></code>).</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.PovScore.white">
<span class="sig-name descname"><span class="pre">white</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference internal" href="#chess.engine.Score" title="chess.engine.Score"><span class="pre">Score</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#PovScore.white"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.PovScore.white" title="Link to this definition"></a></dt>
<dd><p>Gets the score from White’s point of view.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.PovScore.black">
<span class="sig-name descname"><span class="pre">black</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference internal" href="#chess.engine.Score" title="chess.engine.Score"><span class="pre">Score</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#PovScore.black"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.PovScore.black" title="Link to this definition"></a></dt>
<dd><p>Gets the score from Black’s point of view.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.PovScore.pov">
<span class="sig-name descname"><span class="pre">pov</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">color</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">chess.Color</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference internal" href="#chess.engine.Score" title="chess.engine.Score"><span class="pre">Score</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#PovScore.pov"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.PovScore.pov" title="Link to this definition"></a></dt>
<dd><p>Gets the score from the point of view of the given <em>color</em>.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.PovScore.is_mate">
<span class="sig-name descname"><span class="pre">is_mate</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><span class="pre">bool</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#PovScore.is_mate"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.PovScore.is_mate" title="Link to this definition"></a></dt>
<dd><p>Tests if this is a mate score.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.PovScore.wdl">
<span class="sig-name descname"><span class="pre">wdl</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">model</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.Literal" title="(in Python v3.13)"><span class="pre">Literal</span></a><span class="p"><span class="pre">[</span></span><span class="s"><span class="pre">'sf'</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="s"><span class="pre">'sf16.1'</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="s"><span class="pre">'sf16'</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="s"><span class="pre">'sf15.1'</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="s"><span class="pre">'sf15'</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="s"><span class="pre">'sf14'</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="s"><span class="pre">'sf12'</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="s"><span class="pre">'lichess'</span></span><span class="p"><span class="pre">]</span></span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">'sf'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">ply</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">30</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference internal" href="#chess.engine.PovWdl" title="chess.engine.PovWdl"><span class="pre">PovWdl</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#PovScore.wdl"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.PovScore.wdl" title="Link to this definition"></a></dt>
<dd><p>See <a class="reference internal" href="#chess.engine.Score.wdl" title="chess.engine.Score.wdl"><code class="xref py py-func docutils literal notranslate"><span class="pre">wdl()</span></code></a>.</p>
</dd></dl>

</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="chess.engine.Score">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">chess.engine.</span></span><span class="sig-name descname"><span class="pre">Score</span></span><a class="reference internal" href="_modules/chess/engine.html#Score"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.Score" title="Link to this definition"></a></dt>
<dd><p>Evaluation of a position.</p>
<p>The score can be <code class="xref py py-class docutils literal notranslate"><span class="pre">Cp</span></code> (centi-pawns),
<code class="xref py py-class docutils literal notranslate"><span class="pre">Mate</span></code> or <code class="xref py py-data docutils literal notranslate"><span class="pre">MateGiven</span></code>.
A positive value indicates an advantage.</p>
<p>There is a total order defined on centi-pawn and mate scores.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span><span class="w"> </span><span class="nn">chess.engine</span><span class="w"> </span><span class="kn">import</span> <span class="n">Cp</span><span class="p">,</span> <span class="n">Mate</span><span class="p">,</span> <span class="n">MateGiven</span>
<span class="gp">&gt;&gt;&gt;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">Mate</span><span class="p">(</span><span class="o">-</span><span class="mi">0</span><span class="p">)</span> <span class="o">&lt;</span> <span class="n">Mate</span><span class="p">(</span><span class="o">-</span><span class="mi">1</span><span class="p">)</span> <span class="o">&lt;</span> <span class="n">Cp</span><span class="p">(</span><span class="o">-</span><span class="mi">50</span><span class="p">)</span> <span class="o">&lt;</span> <span class="n">Cp</span><span class="p">(</span><span class="mi">200</span><span class="p">)</span> <span class="o">&lt;</span> <span class="n">Mate</span><span class="p">(</span><span class="mi">4</span><span class="p">)</span> <span class="o">&lt;</span> <span class="n">Mate</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="o">&lt;</span> <span class="n">MateGiven</span>
<span class="go">True</span>
</pre></div>
</div>
<p>Scores can be negated to change the point of view:</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="o">-</span><span class="n">Cp</span><span class="p">(</span><span class="mi">20</span><span class="p">)</span>
<span class="go">Cp(-20)</span>
</pre></div>
</div>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="o">-</span><span class="n">Mate</span><span class="p">(</span><span class="o">-</span><span class="mi">4</span><span class="p">)</span>
<span class="go">Mate(+4)</span>
</pre></div>
</div>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="o">-</span><span class="n">Mate</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
<span class="go">MateGiven</span>
</pre></div>
</div>
<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.Score.score">
<em class="property"><span class="pre">abstract</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">score</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">mate_score</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#Score.score"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.Score.score" title="Link to this definition"></a></dt>
<dt class="sig sig-object py">
<em class="property"><span class="pre">abstract</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">score</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">mate_score</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span></span></dt>
<dd><p>Returns the centi-pawn score as an integer or <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
<p>You can optionally pass a large value to convert mate scores to
centi-pawn scores.</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Cp</span><span class="p">(</span><span class="o">-</span><span class="mi">300</span><span class="p">)</span><span class="o">.</span><span class="n">score</span><span class="p">()</span>
<span class="go">-300</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">Mate</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span><span class="o">.</span><span class="n">score</span><span class="p">()</span> <span class="ow">is</span> <span class="kc">None</span>
<span class="go">True</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">Mate</span><span class="p">(</span><span class="mi">5</span><span class="p">)</span><span class="o">.</span><span class="n">score</span><span class="p">(</span><span class="n">mate_score</span><span class="o">=</span><span class="mi">100000</span><span class="p">)</span>
<span class="go">99995</span>
</pre></div>
</div>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.Score.mate">
<em class="property"><span class="pre">abstract</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">mate</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#Score.mate"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.Score.mate" title="Link to this definition"></a></dt>
<dd><p>Returns the number of plies to mate, negative if we are getting
mated, or <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>This conflates <code class="docutils literal notranslate"><span class="pre">Mate(0)</span></code> (we lost) and <code class="docutils literal notranslate"><span class="pre">MateGiven</span></code>
(we won) to <code class="docutils literal notranslate"><span class="pre">0</span></code>.</p>
</div>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.Score.is_mate">
<span class="sig-name descname"><span class="pre">is_mate</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><span class="pre">bool</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#Score.is_mate"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.Score.is_mate" title="Link to this definition"></a></dt>
<dd><p>Tests if this is a mate score.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.Score.wdl">
<em class="property"><span class="pre">abstract</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">wdl</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">model</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.Literal" title="(in Python v3.13)"><span class="pre">Literal</span></a><span class="p"><span class="pre">[</span></span><span class="s"><span class="pre">'sf'</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="s"><span class="pre">'sf16.1'</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="s"><span class="pre">'sf16'</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="s"><span class="pre">'sf15.1'</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="s"><span class="pre">'sf15'</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="s"><span class="pre">'sf14'</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="s"><span class="pre">'sf12'</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><span class="s"><span class="pre">'lichess'</span></span><span class="p"><span class="pre">]</span></span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">'sf'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">ply</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">30</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference internal" href="#chess.engine.Wdl" title="chess.engine.Wdl"><span class="pre">Wdl</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#Score.wdl"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.Score.wdl" title="Link to this definition"></a></dt>
<dd><p>Returns statistics for the expected outcome of this game, based on
a <em>model</em>, given that this score is reached at <em>ply</em>.</p>
<p>Scores have a total order, but it makes little sense to compute
the difference between two scores. For example, going from
<code class="docutils literal notranslate"><span class="pre">Cp(-100)</span></code> to <code class="docutils literal notranslate"><span class="pre">Cp(+100)</span></code> is much more significant than going
from <code class="docutils literal notranslate"><span class="pre">Cp(+300)</span></code> to <code class="docutils literal notranslate"><span class="pre">Cp(+500)</span></code>. It is better to compute differences
of the expectation values for the outcome of the game (based on winning
chances and drawing chances).</p>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Cp</span><span class="p">(</span><span class="mi">100</span><span class="p">)</span><span class="o">.</span><span class="n">wdl</span><span class="p">()</span><span class="o">.</span><span class="n">expectation</span><span class="p">()</span> <span class="o">-</span> <span class="n">Cp</span><span class="p">(</span><span class="o">-</span><span class="mi">100</span><span class="p">)</span><span class="o">.</span><span class="n">wdl</span><span class="p">()</span><span class="o">.</span><span class="n">expectation</span><span class="p">()</span>  
<span class="go">0.379...</span>
</pre></div>
</div>
<div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">Cp</span><span class="p">(</span><span class="mi">500</span><span class="p">)</span><span class="o">.</span><span class="n">wdl</span><span class="p">()</span><span class="o">.</span><span class="n">expectation</span><span class="p">()</span> <span class="o">-</span> <span class="n">Cp</span><span class="p">(</span><span class="mi">300</span><span class="p">)</span><span class="o">.</span><span class="n">wdl</span><span class="p">()</span><span class="o">.</span><span class="n">expectation</span><span class="p">()</span>  
<span class="go">0.015...</span>
</pre></div>
</div>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>model</strong> – <ul>
<li><p><code class="docutils literal notranslate"><span class="pre">sf</span></code>, the WDL model used by the latest Stockfish
(currently <code class="docutils literal notranslate"><span class="pre">sf16</span></code>).</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">sf16</span></code>, the WDL model used by Stockfish 16.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">sf15.1</span></code>, the WDL model used by Stockfish 15.1.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">sf15</span></code>, the WDL model used by Stockfish 15.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">sf14</span></code>, the WDL model used by Stockfish 14.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">sf12</span></code>, the WDL model used by Stockfish 12.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">lichess</span></code>, the win rate model used by Lichess.
Does not use <em>ply</em>, and does not consider drawing chances.</p></li>
</ul>
</p></li>
<li><p><strong>ply</strong> – The number of half-moves played since the starting
position. Models may scale scores slightly differently based on
this. Defaults to middle game.</p></li>
</ul>
</dd>
</dl>
</dd></dl>

</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="chess.engine.PovWdl">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">chess.engine.</span></span><span class="sig-name descname"><span class="pre">PovWdl</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">relative</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="#chess.engine.Wdl" title="chess.engine.Wdl"><span class="pre">Wdl</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">turn</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">chess.Color</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/chess/engine.html#PovWdl"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.PovWdl" title="Link to this definition"></a></dt>
<dd><p>Relative <a class="reference internal" href="#chess.engine.Wdl" title="chess.engine.Wdl"><code class="xref py py-class docutils literal notranslate"><span class="pre">win/draw/loss</span> <span class="pre">statistics</span></code></a> and the point
of view.</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.PovWdl.relative">
<span class="sig-name descname"><span class="pre">relative</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference internal" href="#chess.engine.Wdl" title="chess.engine.Wdl"><span class="pre">Wdl</span></a></em><a class="headerlink" href="#chess.engine.PovWdl.relative" title="Link to this definition"></a></dt>
<dd><p>The relative <a class="reference internal" href="#chess.engine.Wdl" title="chess.engine.Wdl"><code class="xref py py-class docutils literal notranslate"><span class="pre">Wdl</span></code></a>.</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.PovWdl.turn">
<span class="sig-name descname"><span class="pre">turn</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><span class="pre">bool</span></a></em><a class="headerlink" href="#chess.engine.PovWdl.turn" title="Link to this definition"></a></dt>
<dd><p>The point of view (<code class="docutils literal notranslate"><span class="pre">chess.WHITE</span></code> or <code class="docutils literal notranslate"><span class="pre">chess.BLACK</span></code>).</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.PovWdl.white">
<span class="sig-name descname"><span class="pre">white</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference internal" href="#chess.engine.Wdl" title="chess.engine.Wdl"><span class="pre">Wdl</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#PovWdl.white"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.PovWdl.white" title="Link to this definition"></a></dt>
<dd><p>Gets the <a class="reference internal" href="#chess.engine.Wdl" title="chess.engine.Wdl"><code class="xref py py-class docutils literal notranslate"><span class="pre">Wdl</span></code></a> from White’s point of view.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.PovWdl.black">
<span class="sig-name descname"><span class="pre">black</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference internal" href="#chess.engine.Wdl" title="chess.engine.Wdl"><span class="pre">Wdl</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#PovWdl.black"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.PovWdl.black" title="Link to this definition"></a></dt>
<dd><p>Gets the <a class="reference internal" href="#chess.engine.Wdl" title="chess.engine.Wdl"><code class="xref py py-class docutils literal notranslate"><span class="pre">Wdl</span></code></a> from Black’s point of view.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.PovWdl.pov">
<span class="sig-name descname"><span class="pre">pov</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">color</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">chess.Color</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference internal" href="#chess.engine.Wdl" title="chess.engine.Wdl"><span class="pre">Wdl</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#PovWdl.pov"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.PovWdl.pov" title="Link to this definition"></a></dt>
<dd><p>Gets the <a class="reference internal" href="#chess.engine.Wdl" title="chess.engine.Wdl"><code class="xref py py-class docutils literal notranslate"><span class="pre">Wdl</span></code></a> from the point of view of the given
<em>color</em>.</p>
</dd></dl>

</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="chess.engine.Wdl">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">chess.engine.</span></span><span class="sig-name descname"><span class="pre">Wdl</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">wins</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">draws</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">losses</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/chess/engine.html#Wdl"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.Wdl" title="Link to this definition"></a></dt>
<dd><p>Win/draw/loss statistics.</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.Wdl.wins">
<span class="sig-name descname"><span class="pre">wins</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a></em><a class="headerlink" href="#chess.engine.Wdl.wins" title="Link to this definition"></a></dt>
<dd><p>The number of wins.</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.Wdl.draws">
<span class="sig-name descname"><span class="pre">draws</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a></em><a class="headerlink" href="#chess.engine.Wdl.draws" title="Link to this definition"></a></dt>
<dd><p>The number of draws.</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.Wdl.losses">
<span class="sig-name descname"><span class="pre">losses</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a></em><a class="headerlink" href="#chess.engine.Wdl.losses" title="Link to this definition"></a></dt>
<dd><p>The number of losses.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.Wdl.total">
<span class="sig-name descname"><span class="pre">total</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#Wdl.total"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.Wdl.total" title="Link to this definition"></a></dt>
<dd><p>Returns the total number of games. Usually, <code class="docutils literal notranslate"><span class="pre">wdl</span></code> reported by engines
is scaled to 1000 games.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.Wdl.winning_chance">
<span class="sig-name descname"><span class="pre">winning_chance</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><span class="pre">float</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#Wdl.winning_chance"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.Wdl.winning_chance" title="Link to this definition"></a></dt>
<dd><p>Returns the relative frequency of wins.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.Wdl.drawing_chance">
<span class="sig-name descname"><span class="pre">drawing_chance</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><span class="pre">float</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#Wdl.drawing_chance"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.Wdl.drawing_chance" title="Link to this definition"></a></dt>
<dd><p>Returns the relative frequency of draws.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.Wdl.losing_chance">
<span class="sig-name descname"><span class="pre">losing_chance</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><span class="pre">float</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#Wdl.losing_chance"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.Wdl.losing_chance" title="Link to this definition"></a></dt>
<dd><p>Returns the relative frequency of losses.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.Wdl.expectation">
<span class="sig-name descname"><span class="pre">expectation</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><span class="pre">float</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#Wdl.expectation"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.Wdl.expectation" title="Link to this definition"></a></dt>
<dd><p>Returns the expectation value, where a win is valued 1, a draw is
valued 0.5, and a loss is valued 0.</p>
</dd></dl>

</dd></dl>

</section>
<section id="indefinite-or-infinite-analysis">
<h2>Indefinite or infinite analysis<a class="headerlink" href="#indefinite-or-infinite-analysis" title="Link to this heading"></a></h2>
<p>Example: Stream information from the engine and stop on an arbitrary condition.</p>
<div class="literal-block-wrapper docutils container" id="id12">
<div class="code-block-caption"><span class="caption-text">Using synchronous <a class="reference internal" href="#chess.engine.SimpleEngine" title="chess.engine.SimpleEngine"><code class="xref py py-class docutils literal notranslate"><span class="pre">SimpleEngine</span></code></a></span><a class="headerlink" href="#id12" title="Link to this code"></a></div>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="kn">import</span><span class="w"> </span><span class="nn">chess</span>
 <span class="kn">import</span><span class="w"> </span><span class="nn">chess.engine</span>

 <span class="n">engine</span> <span class="o">=</span> <span class="n">chess</span><span class="o">.</span><span class="n">engine</span><span class="o">.</span><span class="n">SimpleEngine</span><span class="o">.</span><span class="n">popen_uci</span><span class="p">(</span><span class="s2">&quot;/usr/bin/stockfish&quot;</span><span class="p">)</span>

 <span class="k">with</span> <span class="n">engine</span><span class="o">.</span><span class="n">analysis</span><span class="p">(</span><span class="n">chess</span><span class="o">.</span><span class="n">Board</span><span class="p">())</span> <span class="k">as</span> <span class="n">analysis</span><span class="p">:</span>
     <span class="k">for</span> <span class="n">info</span> <span class="ow">in</span> <span class="n">analysis</span><span class="p">:</span>
         <span class="nb">print</span><span class="p">(</span><span class="n">info</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;score&quot;</span><span class="p">),</span> <span class="n">info</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;pv&quot;</span><span class="p">))</span>

         <span class="c1"># Arbitrary stop condition.</span>
         <span class="k">if</span> <span class="n">info</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;seldepth&quot;</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span> <span class="o">&gt;</span> <span class="mi">20</span><span class="p">:</span>
             <span class="k">break</span>

 <span class="n">engine</span><span class="o">.</span><span class="n">quit</span><span class="p">()</span>
</pre></div>
</div>
</div>
<div class="literal-block-wrapper docutils container" id="id13">
<div class="code-block-caption"><span class="caption-text">Using asyncio</span><a class="headerlink" href="#id13" title="Link to this code"></a></div>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="kn">import</span><span class="w"> </span><span class="nn">asyncio</span>
 <span class="kn">import</span><span class="w"> </span><span class="nn">chess</span>
 <span class="kn">import</span><span class="w"> </span><span class="nn">chess.engine</span>

 <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="kc">None</span><span class="p">:</span>
     <span class="n">transport</span><span class="p">,</span> <span class="n">engine</span> <span class="o">=</span> <span class="k">await</span> <span class="n">chess</span><span class="o">.</span><span class="n">engine</span><span class="o">.</span><span class="n">popen_uci</span><span class="p">(</span><span class="s2">&quot;/usr/bin/stockfish&quot;</span><span class="p">)</span>

     <span class="k">with</span> <span class="k">await</span> <span class="n">engine</span><span class="o">.</span><span class="n">analysis</span><span class="p">(</span><span class="n">chess</span><span class="o">.</span><span class="n">Board</span><span class="p">())</span> <span class="k">as</span> <span class="n">analysis</span><span class="p">:</span>
         <span class="k">async</span> <span class="k">for</span> <span class="n">info</span> <span class="ow">in</span> <span class="n">analysis</span><span class="p">:</span>
             <span class="nb">print</span><span class="p">(</span><span class="n">info</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;score&quot;</span><span class="p">),</span> <span class="n">info</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;pv&quot;</span><span class="p">))</span>

             <span class="c1"># Arbitrary stop condition.</span>
             <span class="k">if</span> <span class="n">info</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s2">&quot;seldepth&quot;</span><span class="p">,</span> <span class="mi">0</span><span class="p">)</span> <span class="o">&gt;</span> <span class="mi">20</span><span class="p">:</span>
                 <span class="k">break</span>

     <span class="k">await</span> <span class="n">engine</span><span class="o">.</span><span class="n">quit</span><span class="p">()</span>

 <span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">())</span>
</pre></div>
</div>
</div>
<dl class="py class">
<dt class="sig sig-object py" id="id3">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">chess.engine.</span></span><span class="sig-name descname"><span class="pre">Protocol</span></span><a class="reference internal" href="_modules/chess/engine.html#Protocol"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#id3" title="Link to this definition"></a></dt>
<dd><p>Protocol for communicating with a chess engine process.</p>
<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.Protocol.analysis">
<em class="property"><span class="pre">abstract</span><span class="w"> </span><span class="pre">async</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">analysis</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">board:</span> <span class="pre">~chess.Board</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">limit:</span> <span class="pre">~chess.engine.Limit</span> <span class="pre">|</span> <span class="pre">None</span> <span class="pre">=</span> <span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">multipv:</span> <span class="pre">int</span> <span class="pre">|</span> <span class="pre">None</span> <span class="pre">=</span> <span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">game:</span> <span class="pre">object</span> <span class="pre">|</span> <span class="pre">None</span> <span class="pre">=</span> <span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">info:</span> <span class="pre">~chess.engine.Info</span> <span class="pre">=</span> <span class="pre">&lt;Info.ALL:</span> <span class="pre">31&gt;</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">root_moves:</span> <span class="pre">~typing.Iterable[~chess.Move]</span> <span class="pre">|</span> <span class="pre">None</span> <span class="pre">=</span> <span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">options:</span> <span class="pre">~typing.Mapping[str</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">str</span> <span class="pre">|</span> <span class="pre">int</span> <span class="pre">|</span> <span class="pre">bool</span> <span class="pre">|</span> <span class="pre">None]</span> <span class="pre">=</span> <span class="pre">{}</span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference internal" href="#chess.engine.AnalysisResult" title="chess.engine.AnalysisResult"><span class="pre">AnalysisResult</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#Protocol.analysis"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.Protocol.analysis" title="Link to this definition"></a></dt>
<dd><p>Starts analysing a position.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>board</strong> – The position to analyse. The entire move stack will be
sent to the engine.</p></li>
<li><p><strong>limit</strong> – Optional. An instance of <a class="reference internal" href="#chess.engine.Limit" title="chess.engine.Limit"><code class="xref py py-class docutils literal notranslate"><span class="pre">chess.engine.Limit</span></code></a>
that determines when to stop the analysis. Analysis is infinite
by default.</p></li>
<li><p><strong>multipv</strong> – Optional. Analyse multiple root moves.</p></li>
<li><p><strong>game</strong> – Optional. An arbitrary object that identifies the game.
Will automatically inform the engine if the object is not equal
to the previous game (e.g., <code class="docutils literal notranslate"><span class="pre">ucinewgame</span></code>, <code class="docutils literal notranslate"><span class="pre">new</span></code>).</p></li>
<li><p><strong>info</strong> – Selects which information to retrieve from the
engine. <code class="docutils literal notranslate"><span class="pre">INFO_NONE</span></code>, <code class="docutils literal notranslate"><span class="pre">INFO_BASIC</span></code> (basic information that is
trivial to obtain), <code class="docutils literal notranslate"><span class="pre">INFO_SCORE</span></code>, <code class="docutils literal notranslate"><span class="pre">INFO_PV</span></code>,
<code class="docutils literal notranslate"><span class="pre">INFO_REFUTATION</span></code>, <code class="docutils literal notranslate"><span class="pre">INFO_CURRLINE</span></code>, <code class="docutils literal notranslate"><span class="pre">INFO_ALL</span></code> or any
bitwise combination. Some overhead is associated with parsing
extra information.</p></li>
<li><p><strong>root_moves</strong> – Optional. Limit analysis to a list of root moves.</p></li>
<li><p><strong>options</strong> – Optional. A dictionary of engine options for the
analysis. The previous configuration will be restored after the
analysis is complete. You can permanently apply a configuration
with <a class="reference internal" href="#chess.engine.Protocol.configure" title="chess.engine.Protocol.configure"><code class="xref py py-func docutils literal notranslate"><span class="pre">configure()</span></code></a>.</p></li>
</ul>
</dd>
</dl>
<p>Returns <a class="reference internal" href="#chess.engine.AnalysisResult" title="chess.engine.AnalysisResult"><code class="xref py py-class docutils literal notranslate"><span class="pre">AnalysisResult</span></code></a>, a handle that allows
asynchronously iterating over the information sent by the engine
and stopping the analysis at any time.</p>
</dd></dl>

</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="chess.engine.AnalysisResult">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">chess.engine.</span></span><span class="sig-name descname"><span class="pre">AnalysisResult</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">stop</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.Callable" title="(in Python v3.13)"><span class="pre">Callable</span></a><span class="p"><span class="pre">[</span></span><span class="p"><span class="pre">[</span></span><span class="p"><span class="pre">]</span></span><span class="p"><span class="pre">,</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/chess/engine.html#AnalysisResult"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.AnalysisResult" title="Link to this definition"></a></dt>
<dd><p>Handle to ongoing engine analysis.
Returned by <a class="reference internal" href="#chess.engine.Protocol.analysis" title="chess.engine.Protocol.analysis"><code class="xref py py-func docutils literal notranslate"><span class="pre">chess.engine.Protocol.analysis()</span></code></a>.</p>
<p>Can be used to asynchronously iterate over information sent by the engine.</p>
<p>Automatically stops the analysis when used as a context manager.</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.AnalysisResult.multipv">
<span class="sig-name descname"><span class="pre">multipv</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.List" title="(in Python v3.13)"><span class="pre">List</span></a><span class="p"><span class="pre">[</span></span><a class="reference internal" href="#chess.engine.InfoDict" title="chess.engine.InfoDict"><span class="pre">InfoDict</span></a><span class="p"><span class="pre">]</span></span></em><a class="headerlink" href="#chess.engine.AnalysisResult.multipv" title="Link to this definition"></a></dt>
<dd><p>A list of dictionaries with aggregated information sent by the engine.
One item for each root move.</p>
</dd></dl>

<dl class="py property">
<dt class="sig sig-object py" id="chess.engine.AnalysisResult.info">
<em class="property"><span class="pre">property</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">info</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference internal" href="#chess.engine.InfoDict" title="chess.engine.InfoDict"><span class="pre">InfoDict</span></a></em><a class="headerlink" href="#chess.engine.AnalysisResult.info" title="Link to this definition"></a></dt>
<dd><p>A dictionary of aggregated information sent by the engine. This is
actually an alias for <code class="docutils literal notranslate"><span class="pre">multipv[0]</span></code>.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.AnalysisResult.stop">
<span class="sig-name descname"><span class="pre">stop</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#AnalysisResult.stop"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.AnalysisResult.stop" title="Link to this definition"></a></dt>
<dd><p>Stops the analysis as soon as possible.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.AnalysisResult.wait">
<em class="property"><span class="pre">async</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">wait</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference internal" href="#chess.engine.BestMove" title="chess.engine.BestMove"><span class="pre">BestMove</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#AnalysisResult.wait"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.AnalysisResult.wait" title="Link to this definition"></a></dt>
<dd><p>Waits until the analysis is finished.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.AnalysisResult.get">
<em class="property"><span class="pre">async</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">get</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference internal" href="#chess.engine.InfoDict" title="chess.engine.InfoDict"><span class="pre">InfoDict</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#AnalysisResult.get"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.AnalysisResult.get" title="Link to this definition"></a></dt>
<dd><p>Waits for the next dictionary of information from the engine and
returns it.</p>
<p>It might be more convenient to use <code class="docutils literal notranslate"><span class="pre">async</span> <span class="pre">for</span> <span class="pre">info</span> <span class="pre">in</span> <span class="pre">analysis:</span> <span class="pre">...</span></code>.</p>
<dl class="field-list simple">
<dt class="field-odd">Raises<span class="colon">:</span></dt>
<dd class="field-odd"><p><a class="reference internal" href="#chess.engine.AnalysisComplete" title="chess.engine.AnalysisComplete"><code class="xref py py-exc docutils literal notranslate"><span class="pre">chess.engine.AnalysisComplete</span></code></a> if the analysis is
complete (or has been stopped) and all information has been
consumed. Use <code class="xref py py-func docutils literal notranslate"><span class="pre">next()</span></code> if you
prefer to get <code class="docutils literal notranslate"><span class="pre">None</span></code> instead of an exception.</p>
</dd>
</dl>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.AnalysisResult.would_block">
<span class="sig-name descname"><span class="pre">would_block</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><span class="pre">bool</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#AnalysisResult.would_block"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.AnalysisResult.would_block" title="Link to this definition"></a></dt>
<dd><p>Checks if calling <a class="reference internal" href="#chess.engine.AnalysisResult.get" title="chess.engine.AnalysisResult.get"><code class="xref py py-func docutils literal notranslate"><span class="pre">get()</span></code></a>,
calling <code class="xref py py-func docutils literal notranslate"><span class="pre">next()</span></code>,
or advancing the iterator one step would require waiting for the
engine.</p>
<p>These functions would return immediately if information is
pending (queue is not
<a class="reference internal" href="#chess.engine.AnalysisResult.empty" title="chess.engine.AnalysisResult.empty"><code class="xref py py-func docutils literal notranslate"><span class="pre">empty</span></code></a>) or if the search
is finished.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.AnalysisResult.empty">
<span class="sig-name descname"><span class="pre">empty</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><span class="pre">bool</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#AnalysisResult.empty"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.AnalysisResult.empty" title="Link to this definition"></a></dt>
<dd><p>Checks if all current information has been consumed.</p>
<p>If the queue is empty, but the analysis is still ongoing, then further
information can become available in the future.</p>
</dd></dl>

</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="chess.engine.BestMove">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">chess.engine.</span></span><span class="sig-name descname"><span class="pre">BestMove</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">move</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="core.html#chess.Move" title="chess.Move"><span class="pre">Move</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">ponder</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="core.html#chess.Move" title="chess.Move"><span class="pre">Move</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/chess/engine.html#BestMove"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.BestMove" title="Link to this definition"></a></dt>
<dd><p>Returned by <a class="reference internal" href="#chess.engine.AnalysisResult.wait" title="chess.engine.AnalysisResult.wait"><code class="xref py py-func docutils literal notranslate"><span class="pre">chess.engine.AnalysisResult.wait()</span></code></a>.</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.BestMove.move">
<span class="sig-name descname"><span class="pre">move</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference internal" href="core.html#chess.Move" title="chess.Move"><span class="pre">Move</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></em><a class="headerlink" href="#chess.engine.BestMove.move" title="Link to this definition"></a></dt>
<dd><p>The best move according to the engine, or <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.BestMove.ponder">
<span class="sig-name descname"><span class="pre">ponder</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference internal" href="core.html#chess.Move" title="chess.Move"><span class="pre">Move</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></em><a class="headerlink" href="#chess.engine.BestMove.ponder" title="Link to this definition"></a></dt>
<dd><p>The response that the engine expects after <em>move</em>, or <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
</dd></dl>

</dd></dl>

</section>
<section id="options">
<h2>Options<a class="headerlink" href="#options" title="Link to this heading"></a></h2>
<p><code class="xref py py-func docutils literal notranslate"><span class="pre">configure()</span></code>,
<code class="xref py py-func docutils literal notranslate"><span class="pre">play()</span></code>,
<code class="xref py py-func docutils literal notranslate"><span class="pre">analyse()</span></code> and
<code class="xref py py-func docutils literal notranslate"><span class="pre">analysis()</span></code> accept a dictionary of options.</p>
<div class="literal-block-wrapper docutils container" id="id14">
<div class="code-block-caption"><span class="caption-text">Using synchronous <a class="reference internal" href="#chess.engine.SimpleEngine" title="chess.engine.SimpleEngine"><code class="xref py py-class docutils literal notranslate"><span class="pre">SimpleEngine</span></code></a></span><a class="headerlink" href="#id14" title="Link to this code"></a></div>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="kn">import</span><span class="w"> </span><span class="nn">chess.engine</span>

 <span class="n">engine</span> <span class="o">=</span> <span class="n">chess</span><span class="o">.</span><span class="n">engine</span><span class="o">.</span><span class="n">SimpleEngine</span><span class="o">.</span><span class="n">popen_uci</span><span class="p">(</span><span class="s2">&quot;/usr/bin/stockfish&quot;</span><span class="p">)</span>

 <span class="c1"># Check available options.</span>
 <span class="n">engine</span><span class="o">.</span><span class="n">options</span><span class="p">[</span><span class="s2">&quot;Hash&quot;</span><span class="p">]</span>
 <span class="c1"># Option(name=&#39;Hash&#39;, type=&#39;spin&#39;, default=16, min=1, max=131072, var=[])</span>

 <span class="c1"># Set an option.</span>
 <span class="n">engine</span><span class="o">.</span><span class="n">configure</span><span class="p">({</span><span class="s2">&quot;Hash&quot;</span><span class="p">:</span> <span class="mi">32</span><span class="p">})</span>

 <span class="c1"># [...]</span>
</pre></div>
</div>
</div>
<div class="literal-block-wrapper docutils container" id="id15">
<div class="code-block-caption"><span class="caption-text">Using asyncio</span><a class="headerlink" href="#id15" title="Link to this code"></a></div>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="kn">import</span><span class="w"> </span><span class="nn">asyncio</span>
 <span class="kn">import</span><span class="w"> </span><span class="nn">chess.engine</span>

 <span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="kc">None</span><span class="p">:</span>
     <span class="n">transport</span><span class="p">,</span> <span class="n">engine</span> <span class="o">=</span> <span class="k">await</span> <span class="n">chess</span><span class="o">.</span><span class="n">engine</span><span class="o">.</span><span class="n">popen_uci</span><span class="p">(</span><span class="s2">&quot;/usr/bin/stockfish&quot;</span><span class="p">)</span>

     <span class="c1"># Check available options.</span>
     <span class="nb">print</span><span class="p">(</span><span class="n">engine</span><span class="o">.</span><span class="n">options</span><span class="p">[</span><span class="s2">&quot;Hash&quot;</span><span class="p">])</span>
     <span class="c1"># Option(name=&#39;Hash&#39;, type=&#39;spin&#39;, default=16, min=1, max=131072, var=[])</span>

     <span class="c1"># Set an option.</span>
     <span class="k">await</span> <span class="n">engine</span><span class="o">.</span><span class="n">configure</span><span class="p">({</span><span class="s2">&quot;Hash&quot;</span><span class="p">:</span> <span class="mi">32</span><span class="p">})</span>

     <span class="c1"># [...]</span>

 <span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">())</span>
</pre></div>
</div>
</div>
<dl class="py class">
<dt class="sig sig-object py" id="id4">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">chess.engine.</span></span><span class="sig-name descname"><span class="pre">Protocol</span></span><a class="reference internal" href="_modules/chess/engine.html#Protocol"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#id4" title="Link to this definition"></a></dt>
<dd><p>Protocol for communicating with a chess engine process.</p>
<dl class="py property">
<dt class="sig sig-object py" id="chess.engine.Protocol.options">
<em class="property"><span class="pre">abstract</span><span class="w"> </span><span class="pre">property</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">options</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.MutableMapping" title="(in Python v3.13)"><span class="pre">MutableMapping</span></a><span class="p"><span class="pre">[</span></span><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.13)"><span class="pre">str</span></a><span class="p"><span class="pre">,</span></span><span class="w"> </span><a class="reference internal" href="#chess.engine.Option" title="chess.engine.Option"><span class="pre">Option</span></a><span class="p"><span class="pre">]</span></span></em><a class="headerlink" href="#chess.engine.Protocol.options" title="Link to this definition"></a></dt>
<dd><p>Dictionary of available options.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.Protocol.configure">
<em class="property"><span class="pre">abstract</span><span class="w"> </span><span class="pre">async</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">configure</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">options</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.Mapping" title="(in Python v3.13)"><span class="pre">Mapping</span></a><span class="p"><span class="pre">[</span></span><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.13)"><span class="pre">str</span></a><span class="p"><span class="pre">,</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.13)"><span class="pre">str</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><span class="pre">bool</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a><span class="p"><span class="pre">]</span></span></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#Protocol.configure"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.Protocol.configure" title="Link to this definition"></a></dt>
<dd><p>Configures global engine options.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><p><strong>options</strong> – A dictionary of engine options where the keys are
names of <a class="reference internal" href="#chess.engine.Protocol.options" title="chess.engine.Protocol.options"><code class="xref py py-data docutils literal notranslate"><span class="pre">options</span></code></a>. Do not set options
that are managed automatically
(<a class="reference internal" href="#chess.engine.Option.is_managed" title="chess.engine.Option.is_managed"><code class="xref py py-func docutils literal notranslate"><span class="pre">chess.engine.Option.is_managed()</span></code></a>).</p>
</dd>
</dl>
</dd></dl>

</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="chess.engine.Option">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">chess.engine.</span></span><span class="sig-name descname"><span class="pre">Option</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.13)"><span class="pre">str</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">type</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.13)"><span class="pre">str</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">default</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.13)"><span class="pre">str</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><span class="pre">bool</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">min</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">max</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">var</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.List" title="(in Python v3.13)"><span class="pre">List</span></a><span class="p"><span class="pre">[</span></span><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.13)"><span class="pre">str</span></a><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/chess/engine.html#Option"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.Option" title="Link to this definition"></a></dt>
<dd><p>Information about an available engine option.</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.Option.name">
<span class="sig-name descname"><span class="pre">name</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.13)"><span class="pre">str</span></a></em><a class="headerlink" href="#chess.engine.Option.name" title="Link to this definition"></a></dt>
<dd><p>The name of the option.</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.Option.type">
<span class="sig-name descname"><span class="pre">type</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.13)"><span class="pre">str</span></a></em><a class="headerlink" href="#chess.engine.Option.type" title="Link to this definition"></a></dt>
<dd><p>The type of the option.</p>
<table class="docutils align-default">
<thead>
<tr class="row-odd"><th class="head"><p>type</p></th>
<th class="head"><p>UCI</p></th>
<th class="head"><p>CECP</p></th>
<th class="head"><p>value</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>check</p></td>
<td><p>X</p></td>
<td><p>X</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">True</span></code> or <code class="docutils literal notranslate"><span class="pre">False</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>spin</p></td>
<td><p>X</p></td>
<td><p>X</p></td>
<td><p>integer, between <em>min</em> and <em>max</em></p></td>
</tr>
<tr class="row-even"><td><p>combo</p></td>
<td><p>X</p></td>
<td><p>X</p></td>
<td><p>string, one of <em>var</em></p></td>
</tr>
<tr class="row-odd"><td><p>button</p></td>
<td><p>X</p></td>
<td><p>X</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">None</span></code></p></td>
</tr>
<tr class="row-even"><td><p>reset</p></td>
<td></td>
<td><p>X</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">None</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>save</p></td>
<td></td>
<td><p>X</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">None</span></code></p></td>
</tr>
<tr class="row-even"><td><p>string</p></td>
<td><p>X</p></td>
<td><p>X</p></td>
<td><p>string without line breaks</p></td>
</tr>
<tr class="row-odd"><td><p>file</p></td>
<td></td>
<td><p>X</p></td>
<td><p>string, interpreted as the path to a file</p></td>
</tr>
<tr class="row-even"><td><p>path</p></td>
<td></td>
<td><p>X</p></td>
<td><p>string, interpreted as the path to a directory</p></td>
</tr>
</tbody>
</table>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.Option.default">
<span class="sig-name descname"><span class="pre">default</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.13)"><span class="pre">str</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><span class="pre">bool</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></em><a class="headerlink" href="#chess.engine.Option.default" title="Link to this definition"></a></dt>
<dd><p>The default value of the option.</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.Option.min">
<span class="sig-name descname"><span class="pre">min</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></em><a class="headerlink" href="#chess.engine.Option.min" title="Link to this definition"></a></dt>
<dd><p>The minimum integer value of a <em>spin</em> option.</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.Option.max">
<span class="sig-name descname"><span class="pre">max</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></em><a class="headerlink" href="#chess.engine.Option.max" title="Link to this definition"></a></dt>
<dd><p>The maximum integer value of a <em>spin</em> option.</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.Option.var">
<span class="sig-name descname"><span class="pre">var</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.List" title="(in Python v3.13)"><span class="pre">List</span></a><span class="p"><span class="pre">[</span></span><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.13)"><span class="pre">str</span></a><span class="p"><span class="pre">]</span></span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></em><a class="headerlink" href="#chess.engine.Option.var" title="Link to this definition"></a></dt>
<dd><p>A list of allowed string values for a <em>combo</em> option.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.Option.is_managed">
<span class="sig-name descname"><span class="pre">is_managed</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><span class="pre">bool</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#Option.is_managed"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.Option.is_managed" title="Link to this definition"></a></dt>
<dd><p>Some options are managed automatically: <code class="docutils literal notranslate"><span class="pre">UCI_Chess960</span></code>,
<code class="docutils literal notranslate"><span class="pre">UCI_Variant</span></code>, <code class="docutils literal notranslate"><span class="pre">MultiPV</span></code>, <code class="docutils literal notranslate"><span class="pre">Ponder</span></code>.</p>
</dd></dl>

</dd></dl>

</section>
<section id="logging">
<h2>Logging<a class="headerlink" href="#logging" title="Link to this heading"></a></h2>
<p>Communication is logged with debug level on a logger named <code class="docutils literal notranslate"><span class="pre">chess.engine</span></code>.
Debug logs are useful while troubleshooting. Please also provide them
when submitting bug reports.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">logging</span>

<span class="c1"># Enable debug logging.</span>
<span class="n">logging</span><span class="o">.</span><span class="n">basicConfig</span><span class="p">(</span><span class="n">level</span><span class="o">=</span><span class="n">logging</span><span class="o">.</span><span class="n">DEBUG</span><span class="p">)</span>
</pre></div>
</div>
</section>
<section id="asyncssh">
<h2>AsyncSSH<a class="headerlink" href="#asyncssh" title="Link to this heading"></a></h2>
<p><a class="reference internal" href="#id7" title="chess.engine.Protocol"><code class="xref py py-class docutils literal notranslate"><span class="pre">chess.engine.Protocol</span></code></a> can also be used with
<a class="reference external" href="https://asyncssh.readthedocs.io/en/latest/">AsyncSSH</a> (since 1.16.0)
to communicate with an engine on a remote computer.</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">asyncio</span>
<span class="kn">import</span><span class="w"> </span><span class="nn">asyncssh</span>
<span class="kn">import</span><span class="w"> </span><span class="nn">chess</span>
<span class="kn">import</span><span class="w"> </span><span class="nn">chess.engine</span>

<span class="k">async</span> <span class="k">def</span><span class="w"> </span><span class="nf">main</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="kc">None</span><span class="p">:</span>
    <span class="k">async</span> <span class="k">with</span> <span class="n">asyncssh</span><span class="o">.</span><span class="n">connect</span><span class="p">(</span><span class="s2">&quot;localhost&quot;</span><span class="p">)</span> <span class="k">as</span> <span class="n">conn</span><span class="p">:</span>
        <span class="n">channel</span><span class="p">,</span> <span class="n">engine</span> <span class="o">=</span> <span class="k">await</span> <span class="n">conn</span><span class="o">.</span><span class="n">create_subprocess</span><span class="p">(</span><span class="n">chess</span><span class="o">.</span><span class="n">engine</span><span class="o">.</span><span class="n">UciProtocol</span><span class="p">,</span> <span class="s2">&quot;/usr/bin/stockfish&quot;</span><span class="p">)</span>
        <span class="k">await</span> <span class="n">engine</span><span class="o">.</span><span class="n">initialize</span><span class="p">()</span>

        <span class="c1"># Play, analyse, ...</span>
        <span class="k">await</span> <span class="n">engine</span><span class="o">.</span><span class="n">ping</span><span class="p">()</span>

<span class="n">asyncio</span><span class="o">.</span><span class="n">run</span><span class="p">(</span><span class="n">main</span><span class="p">())</span>
</pre></div>
</div>
</section>
<section id="reference">
<h2>Reference<a class="headerlink" href="#reference" title="Link to this heading"></a></h2>
<dl class="py class">
<dt class="sig sig-object py" id="chess.engine.EngineError">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">chess.engine.</span></span><span class="sig-name descname"><span class="pre">EngineError</span></span><a class="reference internal" href="_modules/chess/engine.html#EngineError"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.EngineError" title="Link to this definition"></a></dt>
<dd><p>Runtime error caused by a misbehaving engine or incorrect usage.</p>
</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="chess.engine.EngineTerminatedError">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">chess.engine.</span></span><span class="sig-name descname"><span class="pre">EngineTerminatedError</span></span><a class="reference internal" href="_modules/chess/engine.html#EngineTerminatedError"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.EngineTerminatedError" title="Link to this definition"></a></dt>
<dd><p>The engine process exited unexpectedly.</p>
</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="chess.engine.AnalysisComplete">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">chess.engine.</span></span><span class="sig-name descname"><span class="pre">AnalysisComplete</span></span><a class="reference internal" href="_modules/chess/engine.html#AnalysisComplete"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.AnalysisComplete" title="Link to this definition"></a></dt>
<dd><p>Raised when analysis is complete, all information has been consumed, but
further information was requested.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="chess.engine.popen_uci">
<em class="property"><span class="k"><span class="pre">async</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">chess.engine.</span></span><span class="sig-name descname"><span class="pre">popen_uci</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">command</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.13)"><span class="pre">str</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.List" title="(in Python v3.13)"><span class="pre">List</span></a><span class="p"><span class="pre">[</span></span><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.13)"><span class="pre">str</span></a><span class="p"><span class="pre">]</span></span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">setpgrp</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><span class="pre">bool</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">popen_args</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.Any" title="(in Python v3.13)"><span class="pre">Any</span></a></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.Tuple" title="(in Python v3.13)"><span class="pre">Tuple</span></a><span class="p"><span class="pre">[</span></span><span class="pre">SubprocessTransport</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><a class="reference internal" href="#chess.engine.UciProtocol" title="chess.engine.UciProtocol"><span class="pre">UciProtocol</span></a><span class="p"><span class="pre">]</span></span></span></span><a class="reference internal" href="_modules/chess/engine.html#popen_uci"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.popen_uci" title="Link to this definition"></a></dt>
<dd><p>Spawns and initializes a UCI engine.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>command</strong> – Path of the engine executable, or a list including the
path and arguments.</p></li>
<li><p><strong>setpgrp</strong> – Open the engine process in a new process group. This will
stop signals (such as keyboard interrupts) from propagating from the
parent process. Defaults to <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p></li>
<li><p><strong>popen_args</strong> – Additional arguments for
<a class="reference external" href="https://docs.python.org/3/library/subprocess.html#popen-constructor">popen</a>.
Do not set <code class="docutils literal notranslate"><span class="pre">stdin</span></code>, <code class="docutils literal notranslate"><span class="pre">stdout</span></code>, <code class="docutils literal notranslate"><span class="pre">bufsize</span></code> or
<code class="docutils literal notranslate"><span class="pre">universal_newlines</span></code>.</p></li>
</ul>
</dd>
</dl>
<p>Returns a subprocess transport and engine protocol pair.</p>
</dd></dl>

<dl class="py function">
<dt class="sig sig-object py" id="chess.engine.popen_xboard">
<em class="property"><span class="k"><span class="pre">async</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">chess.engine.</span></span><span class="sig-name descname"><span class="pre">popen_xboard</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">command</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.13)"><span class="pre">str</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.List" title="(in Python v3.13)"><span class="pre">List</span></a><span class="p"><span class="pre">[</span></span><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.13)"><span class="pre">str</span></a><span class="p"><span class="pre">]</span></span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">setpgrp</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><span class="pre">bool</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">popen_args</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.Any" title="(in Python v3.13)"><span class="pre">Any</span></a></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.Tuple" title="(in Python v3.13)"><span class="pre">Tuple</span></a><span class="p"><span class="pre">[</span></span><span class="pre">SubprocessTransport</span><span class="p"><span class="pre">,</span></span><span class="w"> </span><a class="reference internal" href="#chess.engine.XBoardProtocol" title="chess.engine.XBoardProtocol"><span class="pre">XBoardProtocol</span></a><span class="p"><span class="pre">]</span></span></span></span><a class="reference internal" href="_modules/chess/engine.html#popen_xboard"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.popen_xboard" title="Link to this definition"></a></dt>
<dd><p>Spawns and initializes an XBoard engine.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters<span class="colon">:</span></dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>command</strong> – Path of the engine executable, or a list including the
path and arguments.</p></li>
<li><p><strong>setpgrp</strong> – Open the engine process in a new process group. This will
stop signals (such as keyboard interrupts) from propagating from the
parent process. Defaults to <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p></li>
<li><p><strong>popen_args</strong> – <p>Additional arguments for
<a class="reference external" href="https://docs.python.org/3/library/subprocess.html#popen-constructor">popen</a>.
Do not set <code class="docutils literal notranslate"><span class="pre">stdin</span></code>, <code class="docutils literal notranslate"><span class="pre">stdout</span></code>, <code class="docutils literal notranslate"><span class="pre">bufsize</span></code> or
<code class="docutils literal notranslate"><span class="pre">universal_newlines</span></code>.</p>
</p></li>
</ul>
</dd>
</dl>
<p>Returns a subprocess transport and engine protocol pair.</p>
</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="id7">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">chess.engine.</span></span><span class="sig-name descname"><span class="pre">Protocol</span></span><a class="reference internal" href="_modules/chess/engine.html#Protocol"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#id7" title="Link to this definition"></a></dt>
<dd><p>Protocol for communicating with a chess engine process.</p>
<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.Protocol.id">
<span class="sig-name descname"><span class="pre">id</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.Dict" title="(in Python v3.13)"><span class="pre">Dict</span></a><span class="p"><span class="pre">[</span></span><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.13)"><span class="pre">str</span></a><span class="p"><span class="pre">,</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.13)"><span class="pre">str</span></a><span class="p"><span class="pre">]</span></span></em><a class="headerlink" href="#chess.engine.Protocol.id" title="Link to this definition"></a></dt>
<dd><p>Dictionary of information about the engine. Common keys are <code class="docutils literal notranslate"><span class="pre">name</span></code>
and <code class="docutils literal notranslate"><span class="pre">author</span></code>.</p>
</dd></dl>

<dl class="py attribute">
<dt class="sig sig-object py" id="chess.engine.Protocol.returncode">
<span class="sig-name descname"><span class="pre">returncode</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">Future</span><span class="p"><span class="pre">[</span></span><a class="reference external" href="https://docs.python.org/3/library/functions.html#int" title="(in Python v3.13)"><span class="pre">int</span></a><span class="p"><span class="pre">]</span></span></em><a class="headerlink" href="#chess.engine.Protocol.returncode" title="Link to this definition"></a></dt>
<dd><p>Future: Exit code of the process.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.Protocol.initialize">
<em class="property"><span class="pre">abstract</span><span class="w"> </span><span class="pre">async</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">initialize</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#Protocol.initialize"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.Protocol.initialize" title="Link to this definition"></a></dt>
<dd><p>Initializes the engine.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.Protocol.ping">
<em class="property"><span class="pre">abstract</span><span class="w"> </span><span class="pre">async</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">ping</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#Protocol.ping"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.Protocol.ping" title="Link to this definition"></a></dt>
<dd><p>Pings the engine and waits for a response. Used to ensure the engine
is still alive and idle.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.Protocol.quit">
<em class="property"><span class="pre">abstract</span><span class="w"> </span><span class="pre">async</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">quit</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#Protocol.quit"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.Protocol.quit" title="Link to this definition"></a></dt>
<dd><p>Asks the engine to shut down.</p>
</dd></dl>

</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="chess.engine.UciProtocol">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">chess.engine.</span></span><span class="sig-name descname"><span class="pre">UciProtocol</span></span><a class="reference internal" href="_modules/chess/engine.html#UciProtocol"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.UciProtocol" title="Link to this definition"></a></dt>
<dd><p>An implementation of the
<a class="reference external" href="https://www.chessprogramming.org/UCI">Universal Chess Interface</a>
protocol.</p>
</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="chess.engine.XBoardProtocol">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">chess.engine.</span></span><span class="sig-name descname"><span class="pre">XBoardProtocol</span></span><a class="reference internal" href="_modules/chess/engine.html#XBoardProtocol"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.XBoardProtocol" title="Link to this definition"></a></dt>
<dd><p>An implementation of the
<a class="reference external" href="http://hgm.nubati.net/CECP.html">XBoard protocol</a> (CECP).</p>
</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="chess.engine.SimpleEngine">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">chess.engine.</span></span><span class="sig-name descname"><span class="pre">SimpleEngine</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">transport</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">SubprocessTransport</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">protocol</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="#id7" title="chess.engine.Protocol"><span class="pre">Protocol</span></a></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">timeout</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><span class="pre">float</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">10.0</span></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/chess/engine.html#SimpleEngine"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.SimpleEngine" title="Link to this definition"></a></dt>
<dd><p>Synchronous wrapper around a transport and engine protocol pair. Provides
the same methods and attributes as <a class="reference internal" href="#id7" title="chess.engine.Protocol"><code class="xref py py-class docutils literal notranslate"><span class="pre">chess.engine.Protocol</span></code></a>
with blocking functions instead of coroutines.</p>
<p>You may not concurrently modify objects passed to any of the methods. Other
than that, <a class="reference internal" href="#chess.engine.SimpleEngine" title="chess.engine.SimpleEngine"><code class="xref py py-class docutils literal notranslate"><span class="pre">SimpleEngine</span></code></a> is thread-safe. When sending
a new command to the engine, any previous running command will be cancelled
as soon as possible.</p>
<p>Methods will raise <a class="reference external" href="https://docs.python.org/3/library/asyncio-exceptions.html#asyncio.TimeoutError" title="(in Python v3.13)"><code class="xref py py-class docutils literal notranslate"><span class="pre">asyncio.TimeoutError</span></code></a> if an operation takes
<em>timeout</em> seconds longer than expected (unless <em>timeout</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code>).</p>
<p>Automatically closes the transport when used as a context manager.</p>
<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.SimpleEngine.close">
<span class="sig-name descname"><span class="pre">close</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#SimpleEngine.close"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.SimpleEngine.close" title="Link to this definition"></a></dt>
<dd><p>Closes the transport and the background event loop as soon as possible.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.SimpleEngine.popen_uci">
<em class="property"><span class="pre">classmethod</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">popen_uci</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">command</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.13)"><span class="pre">str</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.List" title="(in Python v3.13)"><span class="pre">List</span></a><span class="p"><span class="pre">[</span></span><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.13)"><span class="pre">str</span></a><span class="p"><span class="pre">]</span></span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">timeout</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><span class="pre">float</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">10.0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">debug</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><span class="pre">bool</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">setpgrp</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><span class="pre">bool</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">popen_args</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.Any" title="(in Python v3.13)"><span class="pre">Any</span></a></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference internal" href="#chess.engine.SimpleEngine" title="chess.engine.SimpleEngine"><span class="pre">SimpleEngine</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#SimpleEngine.popen_uci"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.SimpleEngine.popen_uci" title="Link to this definition"></a></dt>
<dd><p>Spawns and initializes a UCI engine.
Returns a <a class="reference internal" href="#chess.engine.SimpleEngine" title="chess.engine.SimpleEngine"><code class="xref py py-class docutils literal notranslate"><span class="pre">SimpleEngine</span></code></a> instance.</p>
</dd></dl>

<dl class="py method">
<dt class="sig sig-object py" id="chess.engine.SimpleEngine.popen_xboard">
<em class="property"><span class="pre">classmethod</span><span class="w"> </span></em><span class="sig-name descname"><span class="pre">popen_xboard</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">command</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.13)"><span class="pre">str</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.List" title="(in Python v3.13)"><span class="pre">List</span></a><span class="p"><span class="pre">[</span></span><a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#str" title="(in Python v3.13)"><span class="pre">str</span></a><span class="p"><span class="pre">]</span></span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">timeout</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#float" title="(in Python v3.13)"><span class="pre">float</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">10.0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">debug</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><span class="pre">bool</span></a><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><a class="reference external" href="https://docs.python.org/3/library/constants.html#None" title="(in Python v3.13)"><span class="pre">None</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">setpgrp</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/functions.html#bool" title="(in Python v3.13)"><span class="pre">bool</span></a></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">popen_args</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference external" href="https://docs.python.org/3/library/typing.html#typing.Any" title="(in Python v3.13)"><span class="pre">Any</span></a></span></em><span class="sig-paren">)</span> <span class="sig-return"><span class="sig-return-icon">&#x2192;</span> <span class="sig-return-typehint"><a class="reference internal" href="#chess.engine.SimpleEngine" title="chess.engine.SimpleEngine"><span class="pre">SimpleEngine</span></a></span></span><a class="reference internal" href="_modules/chess/engine.html#SimpleEngine.popen_xboard"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.SimpleEngine.popen_xboard" title="Link to this definition"></a></dt>
<dd><p>Spawns and initializes an XBoard engine.
Returns a <a class="reference internal" href="#chess.engine.SimpleEngine" title="chess.engine.SimpleEngine"><code class="xref py py-class docutils literal notranslate"><span class="pre">SimpleEngine</span></code></a> instance.</p>
</dd></dl>

</dd></dl>

<dl class="py class">
<dt class="sig sig-object py" id="chess.engine.SimpleAnalysisResult">
<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">chess.engine.</span></span><span class="sig-name descname"><span class="pre">SimpleAnalysisResult</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">simple_engine</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="#chess.engine.SimpleEngine" title="chess.engine.SimpleEngine"><span class="pre">SimpleEngine</span></a></span></em>, <em class="sig-param"><span class="n"><span class="pre">inner</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><a class="reference internal" href="#chess.engine.AnalysisResult" title="chess.engine.AnalysisResult"><span class="pre">AnalysisResult</span></a></span></em><span class="sig-paren">)</span><a class="reference internal" href="_modules/chess/engine.html#SimpleAnalysisResult"><span class="viewcode-link"><span class="pre">[source]</span></span></a><a class="headerlink" href="#chess.engine.SimpleAnalysisResult" title="Link to this definition"></a></dt>
<dd><p>Synchronous wrapper around <a class="reference internal" href="#chess.engine.AnalysisResult" title="chess.engine.AnalysisResult"><code class="xref py py-class docutils literal notranslate"><span class="pre">AnalysisResult</span></code></a>. Returned
by <code class="xref py py-func docutils literal notranslate"><span class="pre">chess.engine.SimpleEngine.analysis()</span></code>.</p>
</dd></dl>

</section>
</section>


           </div>
          </div>
          <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
        <a href="syzygy.html" class="btn btn-neutral float-left" title="Syzygy endgame tablebase probing" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
        <a href="svg.html" class="btn btn-neutral float-right" title="SVG rendering" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
    </div>

  <hr/>

  <div role="contentinfo">
    <p>&#169; Copyright 2014–2024, Niklas Fiekas.</p>
  </div>

  Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
    <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
    provided by <a href="https://readthedocs.org">Read the Docs</a>.
   

</footer>
        </div>
      </div>
    </section>
  </div>
  <script>
      jQuery(function () {
          SphinxRtdTheme.Navigation.enable(true);
      });
  </script> 

</body>
</html>